Hashlock Markets Wallets API

openapi: 3.2.0
info:
  title: Hashlock Markets Wallets API
  version: 1.0.0
  description: 'Guides, concepts and a quickstart: https://docs.hashlock.markets


    Non-custodial cross-chain atomic swaps (BTC ↔ EVM / TRON / Solana) via sealed RFQ + HTLC. Makers and takers share these endpoints. Authenticate with an API key: `Authorization: Bearer hk_...`. **Wallets first.** An order that GIVES an asset requires a proven wallet on that asset''s chain, and your key starts with only the address its account signed in with. `GET /v1/me` lists both what each chain''s `login` address is and what you have `proven`; `POST /v1/wallets/{evm|tron|solana|bitcoin}` proves another by signature — Bitcoin included, on a BIP-322 one. A proof adds trading reach and nothing else: it never becomes the account''s payout identity, which only a wallet session can change — so a key alone cannot redirect anyone''s money. The message you sign for it must say `link this wallet` and carry a nonce from `GET /v1/wallets/nonce`; that nonce is not a login nonce, so the signature you collect is not a session for that wallet''s account. **Rate limits.** Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds). Over the limit returns `429` with `Retry-After`. **Idempotency.** Send an `Idempotency-Key` header on any POST to make retries safe: the operation runs once and the same response is replayed (with `Idempotency-Replayed: true`). Reusing a key with a different body returns `422`. Keys are remembered for 24h — except a `504`, which is a read of ours running out of time: on the builders nothing happened, and on `/tx/broadcast` we cannot tell — so either way a retry with the same key really retries. The fund, claim and refund builders change nothing on the server, so they run on every call and nothing of theirs is remembered — retry them freely. **Custody-agnostic settlement.** The fund/claim/refund endpoints return UNSIGNED transactions; you sign with your own key/HSM and submit via `/v1/tx/broadcast`. The server never holds your keys. ---


    ## Maker feed (WebSocket)


    Polling `GET /v1/rfqs` will not win you flow. `wss:///v1/ws` — the host you selected above — streams every request-for-quote you are eligible for, and takes your quotes back over the same socket. **Handshake.** Connect, then send your key as the first frame. Nothing else is accepted until you do:


    ```json

    { "apiKey": "hk_live_..." }

    ```


    The key needs the `maker` scope (`GET /v1/me` shows what yours has). You get a snapshot, then a readiness marker:


    ```json

    { "type": "snapshot", "rfqs": [ ... ] }

    { "type": "ready" }

    ```


    The snapshot is the **public** book only, and at most **100** entries, newest first. If you need more than that, page `GET /v1/rfqs?cursor=…` after connecting. An RFQ created while the snapshot was being built may appear both in it and in the stream that follows — frames carry the rfq id, so key on it and the duplicate is a no-op. **The stream.** Two kinds, and only two:


    ```json

    { "type": "rfq", "kind": "created", "rfq": { ... } }

    { "type": "rfq", "kind": "cancelled", "rfq": { ... } }

    ```


    `cancelled` means the order left the book, not always that its owner cancelled it: when a listed token **closes** (it no longer passes the listing checks), every public order on it is sent as `cancelled` while its status is unchanged (`open` or `negotiating`); if the token **reopens**, the same orders come back as `created` with their original id and `createdAt`. Treat both as upserts keyed on the id. An RFQ also leaves the book when it **expires** or is **agreed** with another maker, and neither emits a frame. A book you maintain purely from the stream therefore drifts: it keeps orders nobody can take any more, and quoting into one is rejected. Reconcile with a fresh `snapshot` (reconnect) or check `GET /v1/rfqs/{id}` before committing to a price. **What reaches you.** Public RFQs, plus private ones addressed to an address on your account.'
servers:
- url: https://api.hashlock.markets
  description: production
security:
- ApiKey: []
tags:
- name: Wallets
paths:
  /v1/wallets/nonce:
    get:
      summary: A single-use nonce to put in the message you are about to sign
      description: 'Expires shortly and is consumed by the first proof that presents it. It is a LINK nonce: it cannot be spent at a login endpoint, so the signature you collect is not a session. `?purpose=authorize` issues the nonce for the login wallet''s authorisation instead — a separate pool.'
      parameters:
      - name: purpose
        in: query
        required: false
        schema:
          type: string
          enum:
          - link
          - authorize
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  nonce:
                    type: string
      operationId: getWalletsNonce
      tags:
      - Wallets
  /v1/wallets/{address}:
    delete:
      summary: Withdraw a proof this account made
      description: 'Removes the address from what this account can trade from. Reach for it after rotating a leaked key: the proofs made with that key outlive it otherwise. Proofs only — a login address is not one and is not removable here. Putting a proof back needs that wallet to sign again.'
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: withdrawn
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  family:
                    type: string
                  proven:
                    type: boolean
                    enum:
                    - false
        '404':
          description: this account has no proof for that address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: deleteWalletsByAddress
      tags:
      - Wallets
  /v1/wallets/evm:
    post:
      summary: Prove a EVM wallet this account holds
      description: Sign with personal_sign / EIP-191 a message carrying `Hashlock Markets`, the words `link this wallet`, the address itself and a nonce from `GET /v1/wallets/nonce`. Needed before this account can create an order that GIVES a EVM asset. The proof is recorded as a proof — it does not become the account's payout identity, which only a wallet session can set. ALONE it counts for giving on EVM only. Add `authorization` — your LOGIN wallet signing a message that carries `Hashlock Markets`, the words `authorise this wallet`, the address being linked (and, except for a Bitcoin login, the login address) and a nonce from `GET /v1/wallets/nonce?purpose=authorize` — and the wallet also counts as a payout address, a Bitcoin/Solana refund address and a TRON funding wallet, as if linked at hashlock.markets. That is how an agent with no browser trades across chains.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - address
              - message
              - signature
              properties:
                address:
                  type: string
                message:
                  type: string
                signature:
                  type: string
                authorization:
                  type: object
                  description: 'optional: the account''s login wallet vouching for this one (see above)'
                  required:
                  - address
                  - message
                  - signature
                  properties:
                    address:
                      type: string
                    message:
                      type: string
                    signature:
                      type: string
            example:
              address: <your address on that chain>
              message: 'Hashlock Markets — link this wallet.


                Address: <the same address>

                Nonce: <GET /v1/wallets/nonce>'
              signature: <that message, signed by that address>
      responses:
        '200':
          description: proven (repeating a proof you already hold is the same 200); `authorised` says whether it counts beyond EVM giving
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  family:
                    type: string
                    enum:
                    - evm
                  proven:
                    type: boolean
                  authorised:
                    type: boolean
        '400':
          description: bad signature, a message that does not say `link this wallet` (or `authorise this wallet`), an authorisation not signed by this account's login wallet or not naming this address, or a nonce that was never issued / already used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: that wallet belongs to another account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postWalletsEvm
      tags:
      - Wallets
  /v1/wallets/tron:
    post:
      summary: Prove a TRON wallet this account holds
      description: Sign with signMessageV2 a message carrying `Hashlock Markets`, the words `link this wallet`, the address itself and a nonce from `GET /v1/wallets/nonce`. Needed before this account can create an order that GIVES a TRON asset. The proof is recorded as a proof — it does not become the account's payout identity, which only a wallet session can set. ALONE it counts for giving on EVM only. Add `authorization` — your LOGIN wallet signing a message that carries `Hashlock Markets`, the words `authorise this wallet`, the address being linked (and, except for a Bitcoin login, the login address) and a nonce from `GET /v1/wallets/nonce?purpose=authorize` — and the wallet also counts as a payout address, a Bitcoin/Solana refund address and a TRON funding wallet, as if linked at hashlock.markets. That is how an agent with no browser trades across chains.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - address
              - message
              - signature
              properties:
                address:
                  type: string
                message:
                  type: string
                signature:
                  type: string
                authorization:
                  type: object
                  description: 'optional: the account''s login wallet vouching for this one (see above)'
                  required:
                  - address
                  - message
                  - signature
                  properties:
                    address:
                      type: string
                    message:
                      type: string
                    signature:
                      type: string
            example:
              address: <your address on that chain>
              message: 'Hashlock Markets — link this wallet.


                Address: <the same address>

                Nonce: <GET /v1/wallets/nonce>'
              signature: <that message, signed by that address>
      responses:
        '200':
          description: proven (repeating a proof you already hold is the same 200); `authorised` says whether it counts beyond EVM giving
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  family:
                    type: string
                    enum:
                    - tvm
                  proven:
                    type: boolean
                  authorised:
                    type: boolean
        '400':
          description: bad signature, a message that does not say `link this wallet` (or `authorise this wallet`), an authorisation not signed by this account's login wallet or not naming this address, or a nonce that was never issued / already used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: that wallet belongs to another account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postWalletsTron
      tags:
      - Wallets
  /v1/wallets/solana:
    post:
      summary: Prove a Solana wallet this account holds
      description: Sign with ed25519 signMessage, base58 a message carrying `Hashlock Markets`, the words `link this wallet`, the address itself and a nonce from `GET /v1/wallets/nonce`. Needed before this account can create an order that GIVES a Solana asset. The proof is recorded as a proof — it does not become the account's payout identity, which only a wallet session can set. ALONE it counts for giving on EVM only. Add `authorization` — your LOGIN wallet signing a message that carries `Hashlock Markets`, the words `authorise this wallet`, the address being linked (and, except for a Bitcoin login, the login address) and a nonce from `GET /v1/wallets/nonce?purpose=authorize` — and the wallet also counts as a payout address, a Bitcoin/Solana refund address and a TRON funding wallet, as if linked at hashlock.markets. That is how an agent with no browser trades across chains.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - address
              - message
              - signature
              properties:
                address:
                  type: string
                message:
                  type: string
                signature:
                  type: string
                authorization:
                  type: object
                  description: 'optional: the account''s login wallet vouching for this one (see above)'
                  required:
                  - address
                  - message
                  - signature
                  properties:
                    address:
                      type: string
                    message:
                      type: string
                    signature:
                      type: string
            example:
              address: <your address on that chain>
              message: 'Hashlock Markets — link this wallet.


                Address: <the same address>

                Nonce: <GET /v1/wallets/nonce>'
              signature: <that message, signed by that address>
      responses:
        '200':
          description: proven (repeating a proof you already hold is the same 200); `authorised` says whether it counts beyond EVM giving
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  family:
                    type: string
                    enum:
                    - svm
                  proven:
                    type: boolean
                  authorised:
                    type: boolean
        '400':
          description: bad signature, a message that does not say `link this wallet` (or `authorise this wallet`), an authorisation not signed by this account's login wallet or not naming this address, or a nonce that was never issued / already used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: that wallet belongs to another account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postWalletsSolana
      tags:
      - Wallets
  /v1/wallets/bitcoin:
    post:
      summary: Prove a Bitcoin wallet this account holds
      description: Sign with BIP-322 (UniSat / OKX `signMessage(msg, 'bip322-simple')`) a message carrying `Hashlock Markets`, the words `link this wallet`, and a nonce from `GET /v1/wallets/nonce`. Needed before this account can create an order that GIVES a Bitcoin asset. The proof is recorded as a proof — it does not become the account's payout identity, which only a wallet session can set. ALONE it counts for giving on EVM only. Add `authorization` — your LOGIN wallet signing a message that carries `Hashlock Markets`, the words `authorise this wallet`, the address being linked (and, except for a Bitcoin login, the login address) and a nonce from `GET /v1/wallets/nonce?purpose=authorize` — and the wallet also counts as a payout address, a Bitcoin/Solana refund address and a TRON funding wallet, as if linked at hashlock.markets. That is how an agent with no browser trades across chains.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - address
              - message
              - signature
              properties:
                address:
                  type: string
                message:
                  type: string
                signature:
                  type: string
                authorization:
                  type: object
                  description: 'optional: the account''s login wallet vouching for this one (see above)'
                  required:
                  - address
                  - message
                  - signature
                  properties:
                    address:
                      type: string
                    message:
                      type: string
                    signature:
                      type: string
            example:
              address: <your address on that chain>
              message: 'Hashlock Markets — link this wallet.


                Address: <the same address>

                Nonce: <GET /v1/wallets/nonce>'
              signature: <that message, signed by that address>
      responses:
        '200':
          description: proven (repeating a proof you already hold is the same 200); `authorised` says whether it counts beyond EVM giving
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  family:
                    type: string
                    enum:
                    - bitcoin
                  proven:
                    type: boolean
                  authorised:
                    type: boolean
        '400':
          description: bad signature, a message that does not say `link this wallet` (or `authorise this wallet`), an authorisation not signed by this account's login wallet or not naming this address, or a nonce that was never issued / already used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: that wallet belongs to another account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postWalletsBitcoin
      tags:
      - Wallets
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: Client-chosen unique key; retries with the same key replay the first response (24h).
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: 'An API key (hk_live_… / hk_test_…) with read/taker/maker scopes. `read` is read-only: every write except webhooks needs `taker` or `maker` (403 otherwise), and either of those can read too. Creating RFQs and listing tokens need `taker`; quoting needs `maker`.'