Zero Hash Withdrawals API

openapi: 3.2.0
info:
  title: zerohash Withdrawals 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: Withdrawals
  description: Initiate and monitor withdrawals from accounts
paths:
  /withdrawals/requests:
    post:
      tags:
      - Withdrawals
      summary: Create withdrawal request
      description: "Creates new withdrawal requests to be settled. Withdrawal requests created through the API go directly into an APPROVED state. \nTo retrieve withdrawal account IDs use the `GET /withdrawals/digital_asset_addresses` and `GET /withdrawals/fiat_accounts` endpoints."
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Withdrawal request details including account ID, asset, amount, and destination information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequestBody'
      responses:
        '200':
          description: Successfully created withdrawal request. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostWithdrawalRequestsResponse'
        '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'
    get:
      tags:
      - Withdrawals
      summary: Get withdrawal requests
      description: Retrieves a list of all withdrawal requests created by users as part of your participant. Results are limited to the last 2 months.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: participant_code
        in: query
        description: Filters for withdrawal request by a specific `participant_code`
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: Filters for a specific page (pagination)
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter for a specific withdrawal status. Must be provided in upper case.
        required: false
        schema:
          type: string
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          - SETTLED
      - name: gas_price
        in: query
        description: Filter for a specific `gas_price` value. Applies only to ERC-20 withdrawals.
        required: false
        schema:
          type: string
      - name: client_withdrawal_request_id
        in: query
        description: Filter for client withdrawal request id
        required: false
        schema:
          type: string
      - name: requested_timestamp[gt]
        in: query
        description: Filter for withdrawal requests whose `requested_timestamp` is greater than the given Unix timestamp (in milliseconds).
        required: false
        schema:
          type: string
          pattern: ^[0-9]{13,19}$
      - name: requested_timestamp[gte]
        in: query
        description: Filter for withdrawal requests whose `requested_timestamp` is greater than or equal to the given Unix timestamp (in milliseconds).
        required: false
        schema:
          type: string
          pattern: ^[0-9]{13,19}$
      - name: requested_timestamp[e]
        in: query
        description: Filter for withdrawal requests whose `requested_timestamp` equals the given Unix timestamp (in milliseconds).
        required: false
        schema:
          type: string
          pattern: ^[0-9]{13,19}$
      - name: requested_timestamp[lt]
        in: query
        description: Filter for withdrawal requests whose `requested_timestamp` is less than the given Unix timestamp (in milliseconds).
        required: false
        schema:
          type: string
          pattern: ^[0-9]{13,19}$
      - name: requested_timestamp[lte]
        in: query
        description: Filter for withdrawal requests whose `requested_timestamp` is less than or equal to the given Unix timestamp (in milliseconds).
        required: false
        schema:
          type: string
          pattern: ^[0-9]{13,19}$
      - name: on_chain_status
        in: query
        description: Filter for on-chain status
        required: false
        schema:
          type: string
          enum:
          - PENDING
          - CONFIRMED
      - name: account_label
        in: query
        description: Filter for a specific account label
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Successfully retrieved paginated list of withdrawal requests with optional filters: participant_code, page, status, gas_price, client_withdrawal_request_id, requested_timestamp, on_chain_status, account_label.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWithdrawalRequestsResponse'
        '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'
  /withdrawals/requests/{id}:
    get:
      tags:
      - Withdrawals
      summary: Get withdrawal request
      description: Retrieves a specific withdrawal request by `id` associated with your participant or platform.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: id
        in: path
        description: Withdrawal request id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved withdrawal request. including status, amounts, fees, and on-chain confirmation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWithdrawalRequestResponse'
        '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'
    delete:
      tags:
      - Withdrawals
      summary: Delete withdrawal request
      description: Rejects a pending withdrawal request.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: id
        in: path
        description: withdrawal request id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted withdrawal request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteWithdrawalRequestResponse'
        '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'
  /withdrawals/execute:
    post:
      tags:
      - Withdrawals
      summary: Execute withdrawal
      description: Executes a withdrawal that has been previously quoted.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Withdrawal execution details including quote ID and confirmation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalExecuteRequest'
      responses:
        '200':
          description: Successfully executed withdrawal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalExecuteResponse'
        '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'
  /withdrawals/uma:
    post:
      tags:
      - Withdrawals
      summary: Request UMA Withdrawal
      description: Requests a withdrawal to an UMA address (on Lightning Network).
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: UMA withdrawal request details including UMA address and amount.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalUmaRequest'
      responses:
        '200':
          description: Successfully created UMA withdrawal request. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalUmaResponse'
        '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'
  /withdrawals/umalookup/{recipient}:
    get:
      tags:
      - Withdrawals
      summary: Performs an UMA lookup prior to initiating a withdrawal
      description: Verifies UMA address of a recipient and returns details of supported receiving currencies` (on Lightning Network).
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: recipient
        in: path
        required: true
        description: The full UMA address of the withdrawal recipient.
        example: $satoshi@vasp.com
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved UMA lookup result. including the list of currencies the recipient VASP can receive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalUmaLookupResponse'
        '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'
  /withdrawals/digital_asset_addresses:
    get:
      tags:
      - Withdrawals
      summary: Get withdrawal addresses
      description: Retrieves a list of all withdrawal addresses created by users as part of your participant.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: participant_code
        in: query
        description: Filters for withdrawal addresses by a specific `participant_code`
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: Filters for a specific page (pagination)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Successfully retrieved paginated list of withdrawal addresses with optional filters: participant_code, page.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWithdrawalAddressesResponse'
        '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'
  /withdrawals/digital_asset_addresses/{id}:
    get:
      tags:
      - Withdrawals
      summary: Get withdrawal address
      description: Retrieves a specific crypto withdrawal account associated with your participant or platform.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: id
        in: path
        description: withdrawal account id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved crypto withdrawal account. including address, asset, and whitelist details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWithdrawalAccountById'
        '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'
  /withdrawals/locked_network_fee:
    get:
      tags:
      - Withdrawals
      summary: Get withdrawal quote
      description: Returns a locked network fee quote for a planned crypto withdrawal. The returned `withdrawal_quote_id` is valid for 30 seconds and must be passed to POST /withdrawals/execute to complete the withdrawal. Exactly one of `withdrawal_account_id` or `withdrawal_address` must be supplied; if `max_amount` is `false` (the default), `amount` is required.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: participant_code
        in: query
        description: The participant the withdrawal will be debited from. 6-character alphanumeric code.
        required: true
        schema:
          type: string
          minLength: 6
          maxLength: 6
      - name: account_group
        in: query
        description: The `account_group` for the source account. Defaults to the caller's `participant_code` when omitted.
        required: false
        schema:
          type: string
      - name: account_label
        in: query
        description: The `account_label` for the source account. Defaults to `general` when omitted.
        required: false
        schema:
          type: string
          maxLength: 50
      - name: asset
        in: query
        description: The asset code of the asset being withdrawn, e.g. BTC.
        required: true
        schema:
          type: string
      - name: amount
        in: query
        description: The requested withdrawal amount. Required (and must be positive) unless `max_amount` is `true`.
        required: false
        schema:
          type: string
      - name: max_amount
        in: query
        description: When `true`, zerohash will generate a withdrawal for the full available balance of `asset` in the source account; in that case `amount` can be omitted. Defaults to `false`. Accepted as the string `"true"` or `"false"`.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: withdrawal_account_id
        in: query
        description: The `withdrawal_account_id` of the whitelisted destination account. Required when `withdrawal_address` is not provided.
        required: false
        schema:
          type: string
      - name: withdrawal_address
        in: query
        description: The on-chain address that will receive the crypto asset. Required when `withdrawal_account_id` is not provided.
        required: false
        schema:
          type: string
      - name: destination_tag
        in: query
        description: The destination tag or memo ID associated with the transaction. Required when the asset is EOS, XLM, or XRP and `no_destination_tag` is `false`.
        required: false
        schema:
          type: string
      - name: no_destination_tag
        in: query
        description: Whether the destination address requires a destination tag. Required for tag-based assets (EOS, XLM, XRP). zerohash requires `no_destination_tag` to be `false` for EOS. Accepted as the string `"true"` or `"false"`.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Successfully retrieved locked network fee quote. including `withdrawal_quote_id`, `net_withdrawal_quantity`, and the locked network/withdrawal fees.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLockedNetworkFeeResponse'
        '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'
  /withdrawals/fiat_accounts:
    get:
      tags:
      - Withdrawals
      summary: Get fiat accounts
      description: 'Retrieves a list of all whitelisted fiat withdrawal accounts.

        Fiat accounts are currently whitelisted via the Client Portal only.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      responses:
        '200':
          description: Successfully retrieved paginated list of whitelisted fiat withdrawal accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWithdrawalFiatAccountsResponse'
        '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'
  /withdrawals/fiat_accounts/{id}:
    get:
      tags:
      - Withdrawals
      summary: Get fiat account
      description: Retrieves a specific fiat withdrawal account that has been whitelisted.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: id
        in: path
        description: Withdrawal account id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved fiat withdrawal account. including account details and whitelist status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWithdrawalFiatAccountById'
        '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'
  /withdrawals/estimate_network_fee:
    get:
      tags:
      - Withdrawals
      summary: Get network fee estimate
      description: Returns a withdrawal estimation for a given asset.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: underlying
        in: query
        description: the underlying asset for the quote
        required: true
        schema:
          $ref: '#/components/schemas/UnderlyingCurrency'
      - name: quoted_currency
        in: query
        description: the quoted asset for the quote
        required: true
        schema:
          $ref: '#/components/schemas/QuotedCurrency'
      - name: amount
        in: query
        description: the amount of the `underlying` currency
        required: false
        schema:
          type: string
      - name: destination_address
        in: query
        description: The destination_address is the receiving address for the withdrawal request
        required: true
        schema:
          type: string
      - name: contract_call
        in: query
        description: In a future release, this field will denote if the destination address is a smart contract address. False is the only acceptable value for now.
        required: true
        schema:
          type: boolean
      responses:
        '200':
          description: Successfully retrieved network fee estimate. including gas price, network fees, and quoted amounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNetworkEstimateFeeResponse'
        '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'
  /withdrawals/validate_address:
    get:
      tags:
      - Withdrawals
      summary: Validate address
      description: Checks whether a withdrawal address is valid for a given asset. For tag-based assets (e.g. XRP, XLM, EOS), also validates whether a destination tag or memo is required.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: asset
        in: query
        description: The asset symbol
        required: true
        schema:
          type: string
      - name: address
        in: query
        description: The address to validate
        required: true
        schema:
          type: string
      - name: destination_tag
        in: query
        description: Used for tag based assets
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved address validation result. with a `message` string indicating whether the address is valid for the given asset.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GetValidateAddressValidResponse'
                - $ref: '#/components/schemas/GetValidateAddressInvalidResponse'
        '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:
    Code400:
      type: object
      description: Request was rejected by validation or a downstream service. `errors` is an array of human-readable messages; each entry describes a single validation failure or business-rule violation.
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: string
          example:
          - body/amount must be >= 0
          - body/asset is required
    WithdrawalExecuteResponse:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/ExecuteResponse'
    GetWithdrawalFiatAccountById:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/FiatAccountsEntity'
    WithdrawalExecuteRequest:
      type: object
      properties:
        withdrawal_quote_id:
          type: string
          description: The unique id associated with a locked network fee quote
        client_withdrawal_request_id:
          type: string
          description: A unique id for the withdrawal produced by the Platform
        beneficiary_participant_code:
          type: string
          description: The identifier of the participan

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