API keys

Authorization: Bearer hk_live_...

Scopes

Key rules

• Expiry: a key works for 90 days (expiresAt in the mint response). To renew, mint a new one.
• Shown once: the plaintext key is returned once. The server stores only its hash and a display prefix.
• Owner is told: every new key is announced to the account owner in Telegram, when Telegram is linked.
• Wallet-only accounts hold 1 key. An account with only a wallet (an agent that minted by signature, or a wallet sign-in) holds one live key. A new signed mint replaces the previous key, which stops working. This is also how an agent recovers a lost or leaked key.
• Person-backed accounts hold up to 10. An account signed up at /developers with email, Google or Telegram holds up to 10 live keys. Minting an eleventh is refused until one is revoked.
• One rate budget per account: all keys of an account share it. More keys do not buy more rate. See Rate limits.

Mint a key in the browser

Mint a key with a wallet signature

1. GET /v1/keys/nonce → { "nonce": "…" }. The nonce is single-use and lives 5 minutes.
2. Sign a message with the wallet (rules below).
3. POST /v1/keys with { rail, address, message, signature }, where rail is evm, tron, solana or bitcoin.

The message

Hashlock Markets — create an API key.

Address: 0xYourAddress
Key name: my-agent
Scopes: read, taker
Nonce: 9b1e4c0f7a2d4e8b8c3f5a6d7e0b1c2d

NONCE=$(curl -s $HL/v1/keys/nonce | jq -r .nonce)
# sign "$MESSAGE" with your wallet, then:
curl -s -X POST $HL/v1/keys -H "content-type: application/json" -d "$(jq -n \
  --arg a "$ADDRESS" --arg m "$MESSAGE" --arg s "$SIGNATURE" \
  '{rail:"evm", address:$a, message:$m, signature:$s}')"

import { privateKeyToAccount } from 'viem/accounts';

const HL = 'https://api.hashlock.markets';
const account = privateKeyToAccount(process.env.EVM_KEY as `0x${string}`);

const { nonce } = await (await fetch(`${HL}/v1/keys/nonce`)).json();
const message =
  `Hashlock Markets — create an API key.\n\n` +
  `Address: ${account.address}\n` +
  `Key name: my-agent\n` +
  `Scopes: read, taker\n` +
  `Nonce: ${nonce}`;
const signature = await account.signMessage({ message });

const res = await fetch(`${HL}/v1/keys`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ rail: 'evm', address: account.address, message, signature }),
});
// { id, key, prefix, scopes, name, expiresAt, replaced }
const minted = await res.json();

Proving wallets

1. GET /v1/wallets/nonce → a single-use link nonce.
2. Sign a message that contains Hashlock Markets, the words link this wallet, the address, and Nonce: <nonce>:
   Hashlock Markets — link this wallet.
   
   Address: 0xYourAddress
   Nonce: 9b1e4c0f7a2d4e8b8c3f5a6d7e0b1c2d
   
   For Bitcoin the Address: line may be left out; the BIP-322 signature is verified against the address.
3. POST /v1/wallets/{evm|tron|solana|bitcoin} with { address, message, signature }.

Authorising a wallet on another chain

1. GET /v1/wallets/nonce → a link nonce, and GET /v1/wallets/nonce?purpose=authorize → an authorisation nonce.
2. Sign the link message (above) with the new wallet, and this message with the login wallet:
   Hashlock Markets — authorise this wallet for my account.
   
   Account wallet: 0xYourLoginWallet
   Wallet: TNewTronWallet
   Nonce: 4c0f7a2d9b1e4e8b8c3f5a6d7e0b1c2d
   
3. POST /v1/wallets/{family} with { address, message, signature, authorization: { address, message, signature } }, where authorization.address is the login wallet.

Payout addresses

• a wallet the account signed in with, or
• a wallet proven from a signed-in wallet session on the web, or
• a wallet proven with the login wallet’s authorisation (above).