Zero Hash Awards API

openapi: 3.2.0
info:
  title: zerohash Awards 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: Awards
  description: Awards Distribution Service
paths:
  /awards/fund:
    post:
      tags:
      - Awards
      summary: Fund awards account
      description: Define the quantity, quoted currency, and asset that you plan to distribute to customers through the `POST /awards/distribute` endpoint.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Awards fund parameters. Provide either `quantity` (amount of `underlying` to purchase) or `total` (amount of `quoted_currency` to spend) — not both.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAwardsBody'
      responses:
        '201':
          description: Successfully funded awards account. Returns the executed quote and booked trade identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAwardsResponse'
        '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'
  /awards/distribute:
    post:
      tags:
      - Awards
      summary: Distribute awards
      description: Evenly distribute the purchased crypto among the specified customers.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: 'Distribution parameters: the asset purchased via `POST /awards/fund`, the per-participant `quantity`, the list of `participant_codes` receiving the award, and the `quoted_currency` those trades settle in.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAwardsDistributeBody'
      responses:
        '201':
          description: Successfully distributed awards. Returns a confirmation per participant containing the booked `trade_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAwardsDistributeResponse'
        '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:
    UnderlyingCurrency:
      type: string
      description: the underlying asset
      example: BTC
      enum:
      - AAVE.ETH
      - ADA
      - ALGO
      - AVAX
      - BAT.ETH
      - BCH
      - BTC
      - BUSD.ETH
      - COMP.ETH
      - DAI.ETH
      - DOGE
      - DOT
      - EGLD
      - EOS
      - ETC
      - ETH
      - ETH.ARBITRUM
      - GRT.ETH
      - GYEN.ETH
      - HBAR
      - LINK.ETH
      - LTC
      - LUNA
      - MATIC.ETH
      - MATIC.POLYGON
      - MKR.ETH
      - MOB
      - SAND.ETH
      - SOL
      - UNI.ETH
      - USDC.ETH
      - USDC.ALGO
      - USDC.POLYGON
      - USDC.SOL
      - USDC.HBAR
      - USDC.XLM
      - USDC.AVAX
      - USDT.ETH
      - UST
      - WBTC.ETH
      - XEM
      - XLM
      - XRP
      - XTZ
      - ZUSD.ETH
    PostAwardsBody:
      oneOf:
      - title: RFQ Standard - Quantity
        description: Request for quote with `quantity` specified
        type: object
        properties:
          underlying:
            $ref: '#/components/schemas/UnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/QuotedCurrency'
          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:
        - underlying
        - quoted_currency
        - quantity
      - title: RFQ Standard - Total
        description: Request for quote with `total` specified
        type: object
        properties:
          underlying:
            $ref: '#/components/schemas/UnderlyingCurrency'
          quoted_currency:
            $ref: '#/components/schemas/QuotedCurrency'
          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:
        - underlying
        - quoted_currency
        - total
    PostAwardsDistributeBody:
      type: object
      properties:
        asset:
          $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
        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'
        participant_codes:
          type: array
          items:
            type: string
          description: The list of customers to receive `quantity` amount of reward
          example:
          - CUST01
          - CUST02
        quoted_currency:
          $ref: '#/components/schemas/LiquidityEnabledQuotedCurrency'
      required:
      - asset
      - quantity
      - participant_codes
      - quoted_currency
    DynamicFee:
      type: object
      required:
      - name
      - amount
      properties:
        name:
          type: string
          example: sample
        amount:
          type: string
          example: '1.95'
    PostAwardsResponse:
      type: object
      properties:
        message:
          oneOf:
          - type: object
            properties:
              request_id:
                type: string
                description: The identifier of the RFQ
                example: 14f8ebb8-7530-4aa4-bef9-9d73d56313f3
              quote:
                title: RFQ Base Response
                description: Response for a request for quote with base fields specified
                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'
                  underlying:
                    $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
                  asset_cost_notional:
                    type: string
                    description: asset_cost_notional is a field that shows the notional cost of the asset
                    maxLength: 50
                    example: '2.00'
                  spread_notional:
                    type: string
                    description: The notional of the spread applied to the quote
                    maxLength: 50
                    example: '2.12'
                  spread_bps:
                    type: string
                    description: The spread in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  commission_notional:
                    type: string
                    description: The notional commission applied to the quote
                    maxLength: 50
                    example: '5.00'
                  commission_bps:
                    type: string
                    description: The commission in basis points applied to the quote
                    maxLength: 50
                    example: '25'
              trade_id:
                type: string
                description: 'The unique identifier assigned to the trade. Note: the `quote_id` will be saved as the `client_trade_id`.'
                example: ba97133e-ab15-4c86-86c1-86671b8420bc
              trade_ids_list:
                type: array
                description: All `trade_id`s booked as part of this fund call. The first element matches `trade_id`; additional entries represent any settlement / bookkeeping legs.
                items:
                  type: string
                  format: uuid
                example:
                - ba97133e-ab15-4c86-86c1-86671b8420bc
                - ce819fe8-b1d7-43bb-961c-e09ede0988d3
              status:
                type: string
                description: The status of the trade.
                example: Completed
                enum:
                - Completed
                - Rejected
          - type: object
            properties:
              request_id:
                type: string
                description: The identifier of the RFQ
                example: 14f8ebb8-7530-4aa4-bef9-9d73d56313f3
              quote:
                title: RFQ Fees Response
                description: Response for a request for quote with fees specified
                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'
                  underlying:
                    $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
                  asset_cost_notional:
                    type: string
                    description: asset_cost_notional is a field that shows the notional cost of the asset
                    maxLength: 50
                    example: '2.00'
                  spread_notional:
                    type: string
                    description: The notional of the spread applied to the quote
                    maxLength: 50
                    example: '2.12'
                  spread_bps:
                    type: string
                    description: The spread in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  commission_notional:
                    type: string
                    description: The notional commission applied to the quote
                    maxLength: 50
                    example: '5.00'
                  commission_bps:
                    type: string
                    description: The commission in basis points applied to the quote
                    maxLength: 50
                    example: '25'
                  fees:
                    type: array
                    items:
                      $ref: '#/components/schemas/DynamicFee'
              trade_id:
                type: string
                description: 'The unique identifier assigned to the trade. Note: the `quote_id` will be saved as the `client_trade_id`.'
                example: ba97133e-ab15-4c86-86c1-86671b8420bc
              trade_ids_list:
                type: array
                description: All `trade_id`s booked as part of this fund call. The first element matches `trade_id`; additional entries represent any settlement / bookkeeping legs.
                items:
                  type: string
                  format: uuid
                example:
                - ba97133e-ab15-4c86-86c1-86671b8420bc
                - ce819fe8-b1d7-43bb-961c-e09ede0988d3
              status:
                type: string
                description: The status of the trade.
                example: Completed
                enum:
                - Completed
                - Rejected
          - type: object
            properties:
              request_id:
                type: string
                description: The identifier of the RFQ
                example: 14f8ebb8-7530-4aa4-bef9-9d73d56313f3
              quote:
                title: RFQ Payment Processing Fees Response
                description: Response for a request for quote with payment processing fees specified
                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'
                  underlying:
                    $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
                  asset_cost_notional:
                    type: string
                    description: asset_cost_notional is a field that shows the notional cost of the asset
                    maxLength: 50
                    example: '2.00'
                  spread_notional:
                    type: string
                    description: The notional of the spread applied to the quote
                    maxLength: 50
                    example: '2.12'
                  spread_bps:
                    type: string
                    description: The spread in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  commission_notional:
                    type: string
                    description: The notional commission applied to the quote
                    maxLength: 50
                    example: '5.00'
                  commission_bps:
                    type: string
                    description: The commission in basis points applied to the quote
                    maxLength: 50
                    example: '25'
                  fees:
                    type: array
                    items:
                      $ref: '#/components/schemas/DynamicFee'
                  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
              trade_id:
                type: string
                description: 'The unique identifier assigned to the trade. Note: the `quote_id` will be saved as the `client_trade_id`.'
                example: ba97133e-ab15-4c86-86c1-86671b8420bc
              trade_ids_list:
                type: array
                description: All `trade_id`s booked as part of this fund call. The first element matches `trade_id`; additional entries represent any settlement / bookkeeping legs.
                items:
                  type: string
                  format: uuid
                example:
                - ba97133e-ab15-4c86-86c1-86671b8420bc
                - ce819fe8-b1d7-43bb-961c-e09ede0988d3
              status:
                type: string
                description: The status of the trade.
                example: Completed
                enum:
                - Completed
                - Rejected
          - type: object
            properties:
              request_id:
                type: string
                description: The identifier of the RFQ
                example: 14f8ebb8-7530-4aa4-bef9-9d73d56313f3
              quote:
                title: RFQ Response with issuer fees applied
                description: Response for a quote where the token issuer has applied fees.
                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'
                  underlying:
                    $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
                  asset_cost_notional:
                    type: string
                    description: asset_cost_notional is a field that shows the notional cost of the asset
                    maxLength: 50
                    example: '2.00'
                  spread_notional:
                    type: string
                    description: The notional of the spread applied to the quote
                    maxLength: 50
                    example: '2.12'
                  spread_bps:
                    type: string
                    description: The spread in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  commission_notional:
                    type: string
                    description: The notional commission applied to the quote
                    maxLength: 50
                    example: '5.00'
                  commission_bps:
                    type: string
                    description: The commission in basis points applied to the quote
                    maxLength: 50
                    example: '25'
                  issuer_fee_payor_type:
                    type: string
                    description: Quote issuer fee payor type
                    example: CUSTOMER
                    enum:
                    - CUSTOMER
                    - PLATFORM
                  issuer_fee_rate:
                    type: string
                    description: The issuer fee in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  issuer_fee_amount:
                    type: string
                    description: The notional of the issuer fee applied to the quote
                    maxLength: 50
                    example: '1.5'
              trade_id:
                type: string
                description: 'The unique identifier assigned to the trade. Note: the `quote_id` will be saved as the `client_trade_id`.'
                example: ba97133e-ab15-4c86-86c1-86671b8420bc
              trade_ids_list:
                type: array
                description: All `trade_id`s booked as part of this fund call. The first element matches `trade_id`; additional entries represent any settlement / bookkeeping legs.
                items:
                  type: string
                  format: uuid
                example:
                - ba97133e-ab15-4c86-86c1-86671b8420bc
                - ce819fe8-b1d7-43bb-961c-e09ede0988d3
              status:
                type: string
                description: The status of the trade.
                example: Completed
                enum:
                - Completed
                - Rejected
          - type: object
            properties:
              request_id:
                type: string
                description: The identifier of the RFQ
                example: 14f8ebb8-7530-4aa4-bef9-9d73d56313f3
              quote:
                title: RFQ Full Response
                description: Response for a request for quote with all details specified
                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'
                  underlying:
                    $ref: '#/components/schemas/LiquidityEnabledUnderlyingCurrency'
                  asset_cost_notional:
                    type: string
                    description: asset_cost_notional is a field that shows the notional cost of the asset
                    maxLength: 50
                    example: '2.00'
                  spread_notional:
                    type: string
                    description: The notional of the spread applied to the quote
                    maxLength: 50
                    example: '2.12'
                  spread_bps:
                    type: string
                    description: The spread in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  commission_notional:
                    type: string
                    description: The notional commission applied to the quote
                    maxLength: 50
                    example: '5.00'
                  commission_bps:
                    type: string
                    description: The commission in basis points applied to the quote
                    maxLength: 50
                    example: '25'
                  issuer_fee_payor_type:
                    type: string
                    description: Quote issuer fee payor type
                    example: CUSTOMER
                    enum:
                    - CUSTOMER
                    - PLATFORM
                  issuer_fee_rate:
                    type: string
                    description: The issuer fee in basis points applied to the quote
                    maxLength: 50
                    example: '50'
                  issuer_fee_amount:
                    type: string
                    description: The notional of the issuer 

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