Hashlock Markets Threads API

openapi: 3.2.0
info:
  title: Hashlock Markets Threads 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: Threads
paths:
  /v1/threads/{id}:
    get:
      summary: Get a negotiation thread (messages, current terms)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread:
                    $ref: '#/components/schemas/Thread'
                  rfq:
                    $ref: '#/components/schemas/Rfq'
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  swap:
                    oneOf:
                    - $ref: '#/components/schemas/Swap'
                    - type: 'null'
                    description: the swap once both sides accepted, else null
        '400':
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getThreadsById
      tags:
      - Threads
  /v1/threads/{id}/propose:
    post:
      summary: Propose a new price on a thread
      description: 'Proposing a price is agreeing to it: when the counterparty takes it with accept: true (POST /v1/threads/{id}/accept-proposal) the deal is agreed in that step. The initiator agrees only with its hashlock, so it passes it here; an initiator''s proposal without one leaves it to accept after the take.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quoteAmount
              properties:
                quoteAmount:
                  type: string
                  description: base units, at most 8 decimals (fewer when the asset has fewer)
                hashlock:
                  type: string
                  description: 32-byte hex sha256(secret) — the initiator's; ignored from the other side
            example:
              quoteAmount: <amount in base units, integer>
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread:
                    $ref: '#/components/schemas/Thread'
        '400':
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postThreadsByIdPropose
      tags:
      - Threads
  /v1/threads/{id}/accept-proposal:
    post:
      summary: Accept the counterparty's pending price
      description: 'Name the price you are accepting: it is refused if a newer counter has replaced it since you read the thread. With `accept: true` it also accepts the deal at that price in the same transaction — COMMITS, like POST /v1/threads/{id}/accept — and, since proposing a price is agreeing to it, that agrees the deal (unless the proposer is the initiator and proposed without its hashlock — then its accept is left); the initiator taking a counter passes its hashlock here (a hashlock without accept: true is refused). Without accept, the taker''s accept is left afterwards (and the proposer''s too, when it is the initiator and proposed without its hashlock).'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quoteAmount
              properties:
                quoteAmount:
                  type: string
                  description: the pending price, base units — must equal the thread's pendingAmount
                accept:
                  type: boolean
                  description: also accept the deal at this price (one transaction)
                hashlock:
                  type: string
                  description: '32-byte hex sha256(secret); required from the initiator with accept: true'
            example:
              quoteAmount: <the pending price, base units — GET /v1/threads/{id}>
              accept: true
              hashlock: <sha256(secret) hex — the initiator only>
      responses:
        '200':
          description: 'ok — { thread }, or with accept: true { thread, swap? }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptResult'
        '400':
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postThreadsByIdAcceptProposal
      tags:
      - Threads
  /v1/threads/{id}/accept:
    post:
      summary: Accept the current terms — COMMITS, and cannot be undone
      description: 'Name the price you are accepting: it is refused if the terms moved since you read the thread. The initiator (funds the long leg) also passes hashlock = sha256(secret); when BOTH sides accept, the swap is created.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quoteAmount
              properties:
                quoteAmount:
                  type: string
                  description: the current price, base units — must equal the thread's currentQuoteAmount
                hashlock:
                  type: string
                  description: 32-byte hex; required from the initiator
            example:
              quoteAmount: <the current price, base units — GET /v1/threads/{id}>
              hashlock: <sha256(secret), 32-byte hex>
      responses:
        '200':
          description: ok — returns { thread, swap? }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptResult'
        '400':
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postThreadsByIdAccept
      tags:
      - Threads
components:
  schemas:
    Thread:
      type: object
      required:
      - id
      - rfqId
      - takerId
      - makerId
      - status
      - takerAccepted
      - makerAccepted
      - createdAt
      - updatedAt
      description: one maker's negotiation on an RFQ
      properties:
        id:
          type: string
        rfqId:
          type: string
        takerId:
          type: string
        makerId:
          type: string
        status:
          type: string
          enum:
          - open
          - agreed
          - closed
        currentQuoteAmount:
          type:
          - string
          - 'null'
          description: the price on the table, base units
        pendingAmount:
          type:
          - string
          - 'null'
          description: a counter-proposal waiting for the other side, base units
        pendingBy:
          type:
          - string
          - 'null'
          description: who proposed pendingAmount
        takerAccepted:
          type: boolean
        makerAccepted:
          type: boolean
        hashlock:
          type:
          - string
          - 'null'
          description: sha256(secret), hex — the initiator's, once it has accepted
        counterpartyName:
          type:
          - string
          - 'null'
          description: the other party's account name, when they show it; null otherwise
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Message:
      type: object
      required:
      - id
      - threadId
      - senderId
      - kind
      - createdAt
      properties:
        id:
          type: string
        threadId:
          type: string
        senderId:
          type: string
        kind:
          type: string
          enum:
          - text
          - quote
          - accept
        body:
          type:
          - string
          - 'null'
        quoteAmount:
          type:
          - string
          - 'null'
          description: base units, on a quote message
        createdAt:
          type: string
          format: date-time
    FundOutpoint:
      type: object
      properties:
        txid:
          type: string
        vout:
          type: integer
        value:
          type: integer
          description: sats
    AcceptResult:
      type: object
      required:
      - thread
      properties:
        thread:
          $ref: '#/components/schemas/Thread'
        swap:
          $ref: '#/components/schemas/Swap'
          description: present once both sides have accepted — the swap the agreement created
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Rfq:
      type: object
      properties:
        id:
          type: string
        direction:
          type: string
          enum:
          - sell_base
          - buy_base
        baseAssetId:
          type: string
          description: asset uuid — list them with GET /v1/assets
        baseAmount:
          type: string
          description: base units
        quoteAssetId:
          type: string
          description: asset uuid — list them with GET /v1/assets
        status:
          type: string
        expiresAt:
          type: string
          format: date-time
    Swap:
      type: object
      description: leg a = what the maker gives, leg b = what the maker wants
      required:
      - id
      - threadId
      - status
      - makerId
      - takerId
      - initiatorUserId
      - hashlock
      - aAssetId
      - aChain
      - aAmount
      - aTimelock
      - bAssetId
      - bChain
      - bAmount
      - bTimelock
      properties:
        id:
          type: string
        rfqId:
          type:
          - string
          - 'null'
        threadId:
          type: string
        status:
          type: string
        makerId:
          type: string
        takerId:
          type: string
        initiatorUserId:
          type: string
          description: funds the long leg first and holds the secret
        hashlock:
          type: string
          description: sha256(secret), hex
        secretCiphertext:
          type:
          - string
          - 'null'
          description: the secret once revealed on chain; null before
        meta:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: server bookkeeping; `meta.fundIntent[leg].at` is a funding in flight (see fund-intent)
        feeBps:
          type: integer
        feeAmount:
          type: string
          description: base units of feeAssetId, paid by the taker
        feeAssetId:
          type:
          - string
          - 'null'
        aAssetId:
          type: string
        aChain:
          type: string
        aAmount:
          type: string
          description: base units
        aTimelock:
          type: string
          format: date-time
        aPayoutAddress:
          type:
          - string
          - 'null'
        aClaimTo:
          type:
          - string
          - 'null'
          description: 'Bitcoin: where this leg''s claim pays (its receiver''s wallet unless they named another address)'
        aRefundAddress:
          type:
          - string
          - 'null'
        aHtlcAddress:
          type:
          - string
          - 'null'
        aFundTx:
          type:
          - string
          - 'null'
        aFundOutpoints:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FundOutpoint'
          description: 'Bitcoin: the funding outputs a claim or refund spends'
        aClaimTx:
          type:
          - string
          - 'null'
        aRefundTx:
          type:
          - string
          - 'null'
        bAssetId:
          type: string
        bChain:
          type: string
        bAmount:
          type: string
          description: base units
        bTimelock:
          type: string
          format: date-time
        bPayoutAddress:
          type:
          - string
          - 'null'
        bClaimTo:
          type:
          - string
          - 'null'
          description: 'Bitcoin: where this leg''s claim pays (its receiver''s wallet unless they named another address)'
        bRefundAddress:
          type:
          - string
          - 'null'
        bHtlcAddress:
          type:
          - string
          - 'null'
        bFundTx:
          type:
          - string
          - 'null'
        bFundOutpoints:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FundOutpoint'
          description: 'Bitcoin: the funding outputs a claim or refund spends'
        bClaimTx:
          type:
          - string
          - 'null'
        bRefundTx:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  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`.'