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:
parameters:
AccountLabelQuery:
name: account_label
in: query
description: Filter by account label (e.g., `general`, `sub_account_test`). Account labels are used to categorize accounts under a participant. Each participant `account_label` maintains a separate balance and transaction history.
required: false
schema:
type: string
example: general
AssetQuery:
name: asset
in: query
description: Filter by asset code (e.g., BTC, USD, ETH)
required: false
schema:
$ref: '#/components/schemas/Asset'
Signature:
name: X-SCX-SIGNED
in: header
description: HMAC-SHA256 signature of the request, base64-encoded. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for the exact signing formula.
required: true
schema:
type: string
PageQuery:
name: page
in: query
description: Page number for pagination (starts at 1).
required: false
schema:
type: number
minimum: 1
example: 1
Timestamp:
name: X-SCX-TIMESTAMP
in: header
description: Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.
required: true
schema:
type: string
example: '1678901234'
ParticipantCodeQuery:
name: participant_code
in: query
description: Filter by a specific participant code. Always 6 uppercase alphanumeric characters.
required: false
schema:
type: string
pattern: ^[A-Z0-9]{6}$
example: ABCDEF
schemas:
PostBOLT11Response:
type: object
properties:
encoded_invoice:
type: string
description: The encoded BOLT11 invoice the payer should pay to credit the deposit.
example: lnbcrt2u1pndp4y5pp5hgh2...
expiration:
type: string
format: date-time
description: The expiration timestamp in RFC3339 format.
example: '2026-05-04T12:45:00Z'
required:
- encoded_invoice
- expiration
GetFiatAccountsResponse:
type: object
properties:
message:
type: object
description: Map of fiat asset code to the list of deposit accounts available for that asset. Keys present depend on the environment and the requesting participant — possible keys include `USD`, `EUR`, `GBP`, `JPY`, `CAD`, `MXN`.
additionalProperties:
type: array
items:
$ref: '#/components/schemas/FiatAccountEntity'
example:
USD:
- type: united_states_wire
shortName: Cross River Bank
bankName: Cross River Bank
bankPhysicalAddress: 885 Teaneck Road, Teaneck, NJ 07666
accountNumber: '120275918106'
routingNumber: 021214891
recipientName: Zero Hash LLC Customer Trust
recipientPhysicalAddress: 327 N. Aberdeen St., FL 1, Chicago, IL 60607
reference: ABCDEF
allowedWireTypes:
- retail
- institutional
Code503:
type: object
description: 'A downstream dependency was unavailable, timed out, or returned a retryable error. Safe to retry; the response carries a `zh-allow-retry: true` header.'
required:
- error
properties:
error:
type: string
example: Service Unavailable
StateTransitionEntity:
type: object
properties:
fromState:
type: string
description: Previous state
example: pending_settlement
toState:
type: string
description: New state
example: confirmed
timestamp:
type: string
description: Transition timestamp in RFC3339 format
example: '2024-01-01T00:00:00Z'
Code404:
type: object
description: The requested resource does not exist or is not visible to the caller.
required:
- error
properties:
error:
type: string
example: Not Found
PostDepositsFundBody:
# --- 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