Zero Hash Deposits API

openapi: 3.2.0
info:
  title: zerohash Deposits 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: Deposits
  description: Create deposit addressed and monitor deposits to accounts
paths:
  /deposits/crypto:
    get:
      tags:
      - Deposits
      summary: List crypto deposits
      description: Retrieves a paginated list of blockchain deposits. Filter by deposit IDs, account IDs, transaction hashes, assets, states, and timestamps.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: deposit_ids
        in: query
        description: Filter by one or more deposit IDs
        required: false
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      - name: account_ids
        in: query
        description: Filter by one or more account IDs
        required: false
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      - name: transaction_hashes
        in: query
        description: Filter by one or more transaction hashes
        required: false
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      - name: assets
        in: query
        description: Filter by one or more asset codes (e.g. BTC, ETH)
        required: false
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      - name: states
        in: query
        description: Filter by one or more deposit states
        required: false
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      - name: state_reasons
        in: query
        description: Filter by one or more state reasons (e.g. `required_travel_rule_info`). Use with `states=PENDING_COMPLIANCE_REVIEW` to list deposits held for Travel Rule review.
        required: false
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      - name: travel_rule_status
        in: query
        description: Convenience filter for Travel Rule status. `pending` returns all deposits currently held awaiting Travel Rule verification (equivalent to `states=PENDING_COMPLIANCE_REVIEW&state_reasons=required_travel_rule_info`).
        required: false
        schema:
          type: string
          enum:
          - pending
      - name: from_timestamp
        in: query
        description: Filter deposits from this timestamp (inclusive)
        required: false
        schema:
          type: string
      - name: to_timestamp
        in: query
        description: Filter deposits up to this timestamp (inclusive)
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of results to return (1-999)
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor for the next page of results
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCryptoDepositsResponse'
        '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'
  /deposits/crypto/{deposit_id}:
    get:
      tags:
      - Deposits
      summary: Get crypto deposit by ID
      description: Retrieves a single blockchain deposit by its unique deposit ID.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: deposit_id
        in: path
        description: The unique identifier of the deposit
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCryptoDepositByIdResponse'
        '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'
  /deposits/digital_asset_addresses:
    post:
      tags:
      - Deposits
      summary: Create deposit address
      description: Creates a deposit address for a given asset.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details for creating a deposit address, including participant code, asset, and network.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDigitalAssetAddressesBody'
      responses:
        '200':
          description: Successfully created deposit address. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDigitalAssetAddressesResponse'
        '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:
      - Deposits
      summary: List deposit addresses
      description: Retrieves a list of addresses associated with your platform.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: participant_code
        in: query
        description: The participant whose deposit addresses should be returned. Must either match the calling platform or be a customer of the calling platform.
        required: true
        schema:
          type: string
          minLength: 6
          maxLength: 6
          example: ABCDEF
      - name: asset
        in: query
        description: Filter by asset. When omitted, addresses for all assets the participant holds are returned.
        required: false
        schema:
          $ref: '#/components/schemas/Asset'
      - name: inactivity_interval
        in: query
        description: Only return addresses that have been inactive for at least this many days (1–1825).
        required: false
        schema:
          type: number
          minimum: 1
          maximum: 1825
          example: 30
      - name: limit
        in: query
        description: Maximum number of addresses to return (1–100). Defaults to `1`.
        required: false
        schema:
          type: number
          minimum: 1
          maximum: 100
          example: 30
          default: 1
      responses:
        '200':
          description: 'Successfully retrieved paginated list of deposit addresses with optional filters: participant_code, asset, inactivity_interval, limit.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDigitalAddressesResponse'
        '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:
      - Deposits
      summary: Update address owner
      description: 'Assigns a new owner to a digital wallet address. '
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details for updating address ownership, including the addresses and new participant code.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchDigitalAssetAddressesBody'
      responses:
        '200':
          description: Successfully updated digital asset address ownership. Returns the updated resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchDigitalAssetAddressesResponse'
        '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'
  /deposits/bolt11:
    post:
      tags:
      - Deposits
      summary: Create a BOLT11 invoice for deposit
      description: Creates a Lightning Network invoice (BOLT11) to deposit funds to the informed participant account.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details for creating a BOLT11 Lightning Network invoice, including participant code, amount, and description.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBOLT11Body'
      responses:
        '200':
          description: Successfully created BOLT11 Lightning Network invoice. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBOLT11Response'
        '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'
  /deposits/bolt11/test_payment:
    post:
      tags:
      - Deposits
      summary: Create a test payment for a BOLT11 deposit invoice
      description: Simulate a payment of BOLT11 invoice deposit generated by /deposits/bolt11. (CERT only)
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details for simulating a test payment, including the BOLT11 invoice payment request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBOLT11TestPaymentBody'
      responses:
        '200':
          description: Successfully simulated test payment for BOLT11 invoice.
        '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'
  /deposits/fund:
    post:
      tags:
      - Deposits
      summary: Fund account
      description: Funds a specified fiat account in the zerohash CERT environment. This is helpful when automating end-to-end testing or manually validating a feature. Not available in production.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details of the fiat account to fund, including participant code, asset, and amount.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDepositsFundBody'
      responses:
        '201':
          description: Successfully funded fiat account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDepositsFundResponse'
        '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'
  /deposits:
    get:
      tags:
      - Deposits
      summary: List deposits
      description: Retrieves a paginated list of deposits made by you and your customers. Results are limited to the last 2 months.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/PageQuery'
      - $ref: '#/components/parameters/AssetQuery'
      - name: include_customer_deposits
        in: query
        description: Include deposits made by customers of your platform. Defaults to `true`. Ignored when `participant_code` is provided — a participant-scoped request always excludes customer deposits.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'true'
          example: 'true'
      - $ref: '#/components/parameters/ParticipantCodeQuery'
      - $ref: '#/components/parameters/AccountLabelQuery'
      - name: settle_timestamp[gt]
        in: query
        description: Filter for deposits whose settlement timestamp (Unix milliseconds) is strictly greater than the value.
        required: false
        schema:
          type: string
          pattern: ^[0-9]+$
          example: '1678901234567'
      - name: settle_timestamp[gte]
        in: query
        description: Filter for deposits whose settlement timestamp (Unix milliseconds) is greater than or equal to the value.
        required: false
        schema:
          type: string
          pattern: ^[0-9]+$
          example: '1678901234567'
      - name: settle_timestamp[lt]
        in: query
        description: Filter for deposits whose settlement timestamp (Unix milliseconds) is strictly less than the value.
        required: false
        schema:
          type: string
          pattern: ^[0-9]+$
          example: '1678901234567'
      - name: settle_timestamp[lte]
        in: query
        description: Filter for deposits whose settlement timestamp (Unix milliseconds) is less than or equal to the value.
        required: false
        schema:
          type: string
          pattern: ^[0-9]+$
          example: '1678901234567'
      - name: settle_timestamp[e]
        in: query
        description: Filter for deposits whose settlement timestamp (Unix milliseconds) equals the value exactly.
        required: false
        schema:
          type: string
          pattern: ^[0-9]+$
          example: '1678901234567'
      - name: parent_link_id_source
        in: query
        description: Filter deposits by the source system that originated the parent link (e.g. `rest_api`, `sdk`).
        required: false
        schema:
          type: string
          example: rest_api
      responses:
        '200':
          description: Paginated list of deposits, optionally filtered by `asset`, `participant_code`, `account_label`, `settle_timestamp`, or `parent_link_id_source`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDepositsResponse'
        '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'
  /deposits/fiat_accounts:
    get:
      tags:
      - Deposits
      summary: List fiat accounts
      description: Retrieves a list of all fiat accounts. You must include your participant_code in the reference field with any deposit to ensure that funds can be allocated correctly to your participant.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      responses:
        '200':
          description: Successfully retrieved paginated list of fiat accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFiatAccountsResponse'
        '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'
  /deposits/uma:
    post:
      tags:
      - Deposits
      summary: Create UMA address
      description: Creates an UMA address for a given participant.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details for creating a UMA address, including participant code and username.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUMAAddressBody'
      responses:
        '201':
          description: Successfully created UMA address. Returns the created resource with generated IDs and timestamps.
        '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:
      - Deposits
      summary: List UMA addresses
      description: Retrieves a list of UMA addresses associated with your platform.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: participant_code
        in: query
        description: Filters for all addresses associated with a participant_code
        required: false
        schema:
          type: string
      - name: page_size
        in: query
        description: Limits the number of addresses returned in the response
        required: false
        schema:
          type: number
          minimum: 1
          maximum: 1000
          example: 10
          default: 10
      - name: offset
        in: query
        description: Skips over the specified number of addresses in the response
        required: false
        schema:
          type: number
          minimum: 1
          example: 0
          default: 0
      responses:
        '200':
          description: 'Successfully retrieved paginated list of UMA addresses with optional filters: participant_code, page_size, offset.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUMAAddressesResponse'
        '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:
      - Deposits
      summary: Update UMA address
      description: Updates an UMA username for a given participant.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Details for updating a UMA address, including participant code and new username.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUMAAddressBody'
      responses:
        '200':
          description: Successfully updated UMA address. Returns the updated resource.
        '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:
    FiatAccountEntity:
      type: object
      properties:
        type:
          type: string
          enum:
          - united_states_wire
          - international_wire
          - internal_transfer
          description: The type of the fiat account. `united_states_wire` is used for domestic US wire instructions; `international_wire` is used for wires sent from outside the US; `internal_transfer` is used for platform-internal transfers.
          example: united_states_wire
        shortName:
          type: string
          description: Short, display-friendly name of the bank.
          example: BMO Harris
        bankName:
          type: string
          description: Full legal name of the bank.
          example: BMO Harris Bank N.A.
        bankPhysicalAddress:
          type: string
          description: Physical address of the bank.
          example: 115 S LaSalle, 18W, Chicago, IL 60603
        accountNumber:
          type: string
          description: zerohash's account number at the bank.
          example: 440-554-4
        routingNumber:
          type: string
          description: Routing (ABA) number of the bank. Only returned for `united_states_wire` accounts.
          example: 021214891
        swift:
          type: string
          description: SWIFT/BIC code of the bank. Only returned for `international_wire` accounts.
          example: HATRUS44
        recipientName:
          type: string
          description: Name the wire should be addressed to.
          example: Zero Hash LLC
        recipientPhysicalAddress:
          type: string
          description: Physical address of the recipient.
          example: 327 N. Aberdeen St., FL 1, Chicago, IL 60607
        reference:
          type: string
          description: Your participant code. Must be included in the wire reference/memo field so the deposit can be allocated to your account.
          example: ABCDEF
        correspondentBankName:
          type: string
          description: Correspondent bank name. Only returned for `international_wire` accounts when a correspondent is required.
        correspondentBranchName:
          type: string
          description: Correspondent branch name. Only returned for `international_wire` accounts when a correspondent is required.
        correspondentBranchAddress:
          type: string
          description: Correspondent branch address. Only returned for `international_wire` accounts when a correspondent is required.
        correspondentSwift:
          type: string
          description: Correspondent bank SWIFT/BIC. Only returned for `international_wire` accounts when a correspondent is required.
        correspondentAccountNumber:
          type: string
          description: zerohash's account number at the correspondent bank. Only returned for `international_wire` accounts when a correspondent is required.
        allowedWireTypes:
          type: array
          items:
            type: string
            enum:
            - retail
            - institutional
          description: The types of wires allowed for this bank account.
          example:
          - retail
          - institutional
      required:
      - type
      - shortName
      - bankName
      - accountNumber
      - recipientName
      - reference
    PostUMAAddressBody:
      type: object
      properties:
        participant_code:
          type: string
          description: The participant code to create an address for
          example: CUST01
        username:
          type: string
          description: The username displayed on the UMA address excluding the domain
          example: $john
      required:
      - participant_code
      - username
    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
    CryptoDepositEntity:
    

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