Hashlock Markets Rfqs API

openapi: 3.2.0
info:
  title: Hashlock Markets Rfqs 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: Rfqs
paths:
  /v1/rfqs:
    get:
      summary: Order book (open RFQs to quote) — cursor-paginated
      parameters:
      - name: baseAssetId
        in: query
        schema:
          type: string
      - name: quoteAssetId
        in: query
        schema:
          type: string
      - name: direction
        in: query
        schema:
          type: string
          enum:
          - sell_base
          - buy_base
      - name: assetId
        in: query
        description: this asset on either side
        schema:
          type: string
          format: uuid
      - name: chain
        in: query
        description: either leg on this chain, e.g. `bitcoin`, `base`
        schema:
          type: string
      - name: verified
        in: query
        description: '`1` or `true`: both tokens verified (no listed tokens). Any other value, or none, applies no filter.'
        schema:
          type: string
      - name: q
        in: query
        description: a symbol prefix (case-insensitive) or a full contract address, on either token
        schema:
          type: string
          maxLength: 100
      - name: sort
        in: query
        description: '`new` (default): newest first. `expiring`: soonest to expire first. Keep it the same while paging (a cursor from the other sort is a 400). An order reopened while you page can move within the `expiring` order.'
        schema:
          type: string
          enum:
          - new
          - expiring
      - name: limit
        in: query
        description: page size, 1–100 (default 20)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: nextCursor from the previous page, unchanged. One that does not decode is a 400 ("invalid cursor"), not page 1 again.
        schema:
          type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  rfqs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Rfq'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    description: pass as ?cursor for the next page; null = last page
      operationId: getRfqs
      tags:
      - Rfqs
    post:
      summary: 'Create an RFQ (scope: taker)'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRfq'
            example:
              direction: sell_base
              baseAssetId: <asset uuid — GET /v1/assets>
              baseAmount: '50000000'
              quoteAssetId: <asset uuid — GET /v1/assets>
              ttlSeconds: 900
              visibility: public
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                type: object
                properties:
                  rfq:
                    $ref: '#/components/schemas/Rfq'
        '400':
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postRfqs
      tags:
      - Rfqs
  /v1/rfqs/mine:
    get:
      summary: Your own RFQs — private ones included, every status — cursor-paginated
      description: 'The order book lists only public open RFQs. This lists everything you created, newest first: how to find an order whose create call timed out, and its id to cancel it.'
      parameters:
      - name: limit
        in: query
        description: page size, 1–100 (default 20)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: nextCursor from the previous page, unchanged. One that does not decode is a 400 ("invalid cursor"), not page 1 again.
        schema:
          type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  rfqs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Rfq'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    description: pass as ?cursor for the next page; null = last page
      operationId: getRfqsMine
      tags:
      - Rfqs
  /v1/rfqs/{id}/threads:
    get:
      summary: The negotiation threads on an RFQ — every one for its creator, your own for a…
      description: 'How a taker finds the quotes on its RFQ without a webhook: each thread is one maker''s quote. Read one with `GET /v1/threads/{id}`. Newest activity first.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  threads:
                    type: array
                    items:
                      $ref: '#/components/schemas/Thread'
        '404':
          description: no such RFQ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getRfqsByIdThreads
      tags:
      - Rfqs
  /v1/rfqs/{id}:
    get:
      summary: Get an RFQ
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  rfq:
                    $ref: '#/components/schemas/Rfq'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getRfqsById
      tags:
      - Rfqs
  /v1/rfqs/{id}/cancel:
    post:
      summary: 'Withdraw your own RFQ (scope: taker)'
      description: Only before a deal is agreed, and only your own order — the id alone does not cancel someone else's.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  rfq:
                    $ref: '#/components/schemas/Rfq'
        '400':
          description: not yours, already agreed, or already gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postRfqsByIdCancel
      tags:
      - Rfqs
  /v1/rfqs/{id}/quotes:
    post:
      summary: 'Quote an RFQ (scope: maker) — opens a settlement thread'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IdempotencyKey'
      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)
            example:
              quoteAmount: <amount in base units, integer>
      responses:
        '201':
          description: created — your quote, and the thread it opened (or updated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  quote:
                    $ref: '#/components/schemas/Quote'
                  thread:
                    $ref: '#/components/schemas/Thread'
        '400':
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postRfqsByIdQuotes
      tags:
      - Rfqs
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
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Quote:
      type: object
      required:
      - id
      - rfqId
      - makerId
      - quoteAmount
      - status
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        rfqId:
          type: string
        makerId:
          type: string
        quoteAmount:
          type: string
          description: base units
        status:
          type: string
          enum:
          - active
          - accepted
          - rejected
          - withdrawn
          - superseded
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateRfq:
      type: object
      required:
      - direction
      - baseAssetId
      - baseAmount
      - quoteAssetId
      - ttlSeconds
      properties:
        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 (integer string)
        quoteAssetId:
          type: string
          description: asset uuid — list them with GET /v1/assets
        ttlSeconds:
          type: integer
        visibility:
          type: string
          enum:
          - public
          - private
        askAmount:
          type: string
          description: a private order's price, base units, at most 8 decimals (fewer when the asset has fewer)
        targetAddress:
          type: string
    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
  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).
  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`.'