Zero Hash Liquidity API

openapi: 3.2.0
info:
  title: zerohash Liquidity API
  description: '

    ### Authentication


    zerohash Uses HMAC SHA-256 verification to ensure the authenticity of API requests, follow instructions by link [https://docs.zerohash.com/reference/api-authentication](https://docs.zerohash.com/reference/api-authentication)


    <a href="/zh-swagger.json">Download zerohash OpenAPI Schema as JSON</a>

    '
  version: 1.7.0
servers:
- url: https://api.cert.zerohash.com
  description: Certification API server
security:
- apiKey: []
  apiPassphrase: []
tags:
- name: Liquidity
  description: Request For Quote and Execution Services
paths:
  /liquidity/rfq:
    get:
      tags:
      - Liquidity
      summary: Get quote
      description: Retrieves a quote for the purchase or sale of a given asset. Exactly one of `quantity` or `total` must be provided.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: side
        in: query
        description: Allows platforms to specify the side of the quote
        required: true
        schema:
          type: string
          enum:
          - buy
          - sell
      - name: underlying
        in: query
        description: Allows platforms to specify the underlying asset
        required: true
        schema:
          $ref: '#/components/schemas/UnderlyingCurrency'
      - name: quoted_currency
        in: query
        description: Allows platforms to specify the quoted asset
        required: true
        schema:
          $ref: '#/components/schemas/QuotedCurrency'
      - name: quantity
        in: query
        description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
        required: false
        schema:
          type: string
      - name: total
        in: query
        description: The `total` of the `quoted_currency` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
        required: false
        schema:
          type: string
      - name: participant_code
        in: query
        description: The participant requesting a quote to buy or sell an asset
        required: false
        schema:
          type: string
      - name: account_label
        in: query
        description: The account_label that's used to fund the trade
        required: false
        schema:
          type: string
      - name: spread
        in: query
        description: Optional custom spread in basis points applied to the quote. Requires the platform to be configured to pass spread through this endpoint.
        required: false
        schema:
          type: string
      - name: commission
        in: query
        description: Optional custom commission in basis points applied to the quote. Mutually exclusive with `spread`; only available to platforms with `spread_as_commission` enabled.
        required: false
        schema:
          type: string
      - name: quote_expiry
        in: query
        description: Optional quote expiration window. Feature-flag gated per platform.
        required: false
        schema:
          type: string
          enum:
          - 5s
          - 30s
          - 1m
          - 5m
          - 10m
          - 15m
      responses:
        '200':
          description: 'Successfully retrieved quote. Returns the quote envelope (`{ message: {...} }`) with pricing and an ephemeral `quote_id`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRequestForQuoteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
    post:
      tags:
      - Liquidity
      summary: Get quote
      description: Retrieves a quote for the purchase or sale of a given asset. Exactly one of `quantity` or `total` must be supplied in the request body.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Request for quote parameters. Select the variant that matches whether the quote includes custom spread, fees, or payment processor metadata.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRequestForQuoteBody'
      responses:
        '201':
          description: 'Successfully generated quote. Returns the quote envelope (`{ message: {...} }`) with pricing and an ephemeral `quote_id`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostRequestForQuoteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
    patch:
      tags:
      - Liquidity
      summary: Update quote
      description: Updates an active quote's `total` (and optionally its `fees`) before execution. The `quote_id` and new `total` are both required.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: 'Quote update parameters: `quote_id` identifying the active quote to update, the new `total`, and an optional replacement `fees` array.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchRequestForQuoteBody'
      responses:
        '200':
          description: 'Successfully updated quote. Returns the updated quote envelope (`{ message: {...} }`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchRequestForQuoteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /liquidity/execute:
    post:
      tags:
      - Liquidity
      summary: Execute quote
      description: Executes the quote identified by `quote_id`. Returns the executed quote, the booked `trade_id`(s), and the trade status.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: 'Execution parameters: the `quote_id` to execute, with optional `funding_details` required for ACH-funded execution flows.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostExecuteQuoteBody'
      responses:
        '200':
          description: Successfully executed quote. Returns the executed quote, the booked `trade_id`, and the trade status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostExecuteQuoteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
components:
  schemas:
    PostExecuteQuoteBody:
      type: object
      properties:
        quote_id:
          type: string
          description: 'The identifier for the quote

            Note: this is required to execute the quote'
          example: 32ad471b-824e-4f04-94ff-45c4439b4fe9
        withdrawal_request_id:
          type: string
          description: Optional withdrawal request ID to associate with the execution. Used by flows that pre-create a withdrawal record and then execute a quote against it.
          example: a81bc81b-dead-4e5d-abff-90865d1e13b1
        always_allocate:
          type: boolean
          description: When true, force allocation of the trade even if the quote has expired or partially filled.
          example: false
        funding_details:
          type: object
          description: ACH funding details, required only for ACH-funded executions. Supply either an `inbound_reference_id` (to settle against an already-received inbound) or the `external_account_id`/`description`/`bank_fee` trio (to initiate a new ACH pull).
          oneOf:
          - type: object
            title: Funding Details Object - Inbound ACH Transfer
            description: Funding details for an inbound ACH transfer. `inbound_reference_id` is the unique identifier for the payment.
            additionalProperties: false
            required:
            - inbound_reference_id
            properties:
              inbound_reference_id:
                type: string
                description: Reference ID of an already-received inbound ACH payment to settle this trade against.
          - type: object
            title: Funding Details Object - External Account
            description: Funding details for an external account transfer.
            additionalProperties: false
            required:
            - external_account_id
            - description
            - bank_fee
            properties:
              external_account_id:
                type: string
                description: Registered external bank account to pull funds from.
              description:
                type: string
                maxLength: 10
                description: Short free-form description written to the ACH statement (max 10 characters).
              bank_fee:
                type: string
                description: Bank fee notional (decimal string) applied to this ACH pull.
      required:
      - quote_id
    LiquidityEnabledQuotedCurrency:
      type: string
      description: The quoted currency in the trading pair. E.g. `USD` in the pair `BTC/USD`.
      example: USD
      enum:
      - USD
      - EUR
    Code503:
      type: object
      description: 'A downstream dependency was unavailable, timed out, or returned a retryable error. Safe to retry; the response carries a `zh-allow-retry: true` header.'
      required:
      - error
      properties:
        error:
          type: string
          example: Service Unavailable
    Code404:
      type: object
      description: The requested resource does not exist or is not visible to the caller.
      required:
      - error
      properties:
        error:
          type: string
          example: Not Found
    PostRequestForQuoteBody:
      oneOf:
      - title: RFQ Base - Quantity
        description: Request for quote with `quantity` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          quantity:
            type: string
            description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '1.00'
        required:
        - side
        - underlying
        - quoted_currency
        - quantity
      - title: RFQ Base - Total
        description: Request for quote with `total` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          total:
            type: string
            description: The total amount of the `quoted_currency` requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '3600.00'
        required:
        - side
        - underlying
        - quoted_currency
        - total
      - title: RFQ Custom Spread - Quantity
        description: Request for quote with custom `spread` and `quantity` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          quantity:
            type: string
            description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '1.00'
          spread:
            type: string
            description: Define the quote spread in basis points
            example: '30'
        required:
        - side
        - underlying
        - quoted_currency
        - quantity
      - title: RFQ Custom Spread - Total
        description: Request for quote with custom `spread` and `total` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          total:
            type: string
            description: The total amount of the `quoted_currency` requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '3600.00'
          spread:
            type: string
            description: Define the quote spread in basis points
            example: '30'
        required:
        - side
        - underlying
        - quoted_currency
        - total
      - title: RFQ Custom Commission - Quantity
        description: Request for quote with custom `commission` and `quantity` specified. Only allowed when the commission feature is enabled.
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          quantity:
            type: string
            description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '1.00'
          commission:
            type: string
            description: Define the quote commission in basis points. Only allowed when the commission feature is enabled for the platform. Mutually exclusive with spread.
            example: '30'
        required:
        - side
        - underlying
        - quoted_currency
        - quantity
      - title: RFQ Custom Commission - Total
        description: Request for quote with custom `commission` and `total` specified. Only allowed when the commission feature is enabled.
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          total:
            type: string
            description: The total amount of the `quoted_currency` requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '3600.00'
          commission:
            type: string
            description: Define the quote commission in basis points. Only allowed when the commission feature is enabled for the platform. Mutually exclusive with spread.
            example: '30'
        required:
        - side
        - underlying
        - quoted_currency
        - total
      - title: RFQ Fees - Quantity
        description: Request for quote with `quantity` and `fees` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          quantity:
            type: string
            description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '1.00'
          fees:
            type: array
            items:
              $ref: '#/components/schemas/DynamicFeeRequest'
        required:
        - side
        - underlying
        - quoted_currency
        - quantity
        - fees
      - title: RFQ Fees - Total
        description: Request for quote with `total` and `fees` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          total:
            type: string
            description: The total amount of the `quoted_currency` requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '3600.00'
          fees:
            type: array
            items:
              $ref: '#/components/schemas/DynamicFeeRequest'
        required:
        - side
        - underlying
        - quoted_currency
        - total
        - fees
      - title: RFQ Payment Processor Fees - Quantity
        description: Request for quote with `quantity`, `fees`, and `payment_processor` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          quantity:
            type: string
            description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '1.00'
          fees:
            type: array
            items:
              $ref: '#/components/schemas/DynamicFeeRequest'
          payment_processor:
            type: object
            properties:
              name:
                type: string
                description: The name of the payment processor
                example: checkout.com
              id:
                type: string
                description: The unique identifier of the payment according to the PSP
                example: 593dd810-f051-40a9-9f26-d45280efe8f3
        required:
        - side
        - underlying
        - quoted_currency
        - quantity
        - fees
        - payment_processor
      - title: RFQ Payment Processor Fees - Total
        description: Request for quote with `total`, `fees`, and `payment_processor` specified
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          total:
            type: string
            description: The total amount of the `quoted_currency` requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '3600.00'
          fees:
            type: array
            items:
              $ref: '#/components/schemas/DynamicFeeRequest'
          payment_processor:
            type: object
            properties:
              name:
                type: string
                description: The name of the payment processor
                example: checkout.com
              id:
                type: string
                description: The unique identifier of the payment according to the PSP
                example: 593dd810-f051-40a9-9f26-d45280efe8f3
        required:
        - side
        - underlying
        - quoted_currency
        - total
        - fees
        - payment_processor
      - title: RFQ Full response
        description: Full response object for a request for quote
        type: object
        properties:
          participant_code:
            type: string
            description: The participant code
            example: CUST01
          account_label:
            type: string
            description: The account_label that's used to fund the trade. Case sensitive.
            example: general
          side:
            type: string
            enum:
            - buy
            - sell
            description: The side of the transaction
            example: buy
          underlying:
            $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
          quantity:
            type: string
            description: The `quantity` of the `underlying` asset requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '1.00'
          total:
            type: string
            description: The total amount of the `quoted_currency` requested in the quote. Exactly one of `quantity` or `total` must be supplied.
            example: '3600.00'
          fees:
            type: array
            items:
              $ref: '#/components/schemas/DynamicFeeRequest'
          spread:
            type: string
            description: Define the quote spread in basis points
            example: '30'
          commission:
            type: string
            description: Define the quote commission in basis points. Only allowed when the commission feature is enabled for the platform. Mutually exclusive with spread.
            example: '30'
          payment_processor:
            type: object
            properties:
              name:
                type: string
                description: The name of the payment processor
                example: checkout.com
              id:
                type: string
                description: The unique identifier of the payment according to the PSP
                example: 593dd810-f051-40a9-9f26-d45280efe8f3
          quote_expiry:
            type: string
            description: Quote expiration
            example: 5s
            enum:
            - 5s
            - 30s
            - 1m
            - 5m
            - 10m
            - 15m
          settlement_type:
            type: string
            description: Quote settlement type
            example: STANDARD
            enum:
            - STANDARD
    OBOParticipantEntity:
      type: object
      properties:
        participant_code:
          type: string
          description: The identifier of the participant making the request
          example: 20XRLH
        account_group:
          type: string
          description: The identifier of the the account group
          example: WRD1K0
        account_label:
          type: string
          description: The account label associated with the account
          example: general
    GetRequestForQuoteResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            request_id:
              type: string
              description: The identifier of the RFQ
              example: ce819fe8-b1d7-43bb-961c-e09ede0988d3
            participant_code:
              type: string
              description: The identifier of the participant making the quote request
              example: CUST01
            quoted_currency:
              $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
            side:
              type: string
              description: The participant side of the quote - `buy` or `sell`.
              example: buy
              enum:
              - buy
              - sell
            quantity:
              type: string
              description: The amount of the underlying currency
              example: '1'
            price:
              type: string
              description: The cost per unit of underlying currency
              example: '11430.90'
            quote_id:
              type: string
              description: 'The identifier for the quote

                Note: this is required to execute the quote'
              example: 32ad471b-824e-4f04-94ff-45c4439b4fe9
            expire_ts:
              type: number
              description: Timestamp when the quote will expire
              example: 1568311649602
            account_group:
              type: string
              description: The group that the account is a part of
              example: GRP001
            account_label:
              type: string
              description: The account label associated with the account
              example: sub_account_test
            obo_participant:
              $ref: '#/components/schemas/OBOParticipantEntity'
            total_notional:
              type: string
              description: Total notional is the full cost inclusive of fees or the total proceeds after fees
              example: '2.00'
            settlement_type:
              type: string
              nullable: true
              description: Quote settlement type. Returns `null` for quotes without an explicit settlement override.
              example: STANDARD
              enum:
              - STANDARD
              - null
            issuer_fee_payor_type:
              type: string
              nullable: true
              description: Indicates which party bears the issuer fee on this quote. Returns `null` when no issuer fee is applied.
              example: null
   

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zero-hash/refs/heads/main/openapi/zero-hash-liquidity-api-openapi.yml