--- updatedAt: 2026-06-02T20:06:00.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # Get withdrawal requests Retrieves a list of all withdrawal requests created by users as part of your participant. Results are limited to the last 2 months. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "zerohash API", "description": "\n### Authentication\n\nzerohash 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)\n\nDownload zerohash OpenAPI Schema as JSON\n", "version": "1.7.0" }, "servers": [ { "url": "https://api.cert.zerohash.com", "description": "Certification API server" } ], "x-readme": { "proxy-enabled": false }, "tags": [ { "name": "Withdrawals", "description": "Initiate and monitor withdrawals from accounts" } ], "paths": { "/withdrawals/requests": { "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" } } } } } } } }, "security": [ { "apiKey": [], "apiPassphrase": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Your API public key. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for how to obtain keys.", "in": "header", "name": "X-SCX-API-KEY" }, "apiPassphrase": { "type": "apiKey", "description": "The passphrase associated with your API key, set when the key was created.", "in": "header", "name": "X-SCX-PASSPHRASE" } }, "parameters": { "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" } }, "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" } } }, "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" ] } } }, "Code403": { "type": "object", "description": "Authentication or authorization failed. `error` is always `true`; `message` explains which check failed (missing API key, bad signature, insufficient permission, etc.).", "required": [ "error", "message" ], "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This api key does not have write permission to this endpoint" } } }, "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" } } }, "Code500": { "type": "object", "description": "An unexpected error occurred on the server. The request can be retried after a short delay, but the same inputs may reproduce the error.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Internal Server Error" } } }, "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" } } }, "GetWithdrawalRequestsResponse": { "type": "object", "properties": { "message": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalRequestEntity" } }, "page": { "type": "number", "example": 1 }, "page_size": { "type": "number", "example": 15 }, "total_pages": { "type": "number", "example": 1 }, "count": { "type": "number", "example": 1 } } }, "WithdrawalRequestEntity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier (UUID v4) for the withdrawal request.", "example": "9084dd8f-ab9f-4f9b-a22b-49bdb4915a93" }, "withdrawal_account_id": { "type": "number", "description": "The ID of the whitelisted withdrawal account or address the funds were sent to.", "example": 3709509 }, "participant_code": { "type": "string", "description": "The participant the request belongs to, e.g. ABCDEF.", "example": "ABCDEF" }, "beneficiary_participant_code": { "type": "string", "nullable": true, "description": "The participant code of the beneficiary when the withdrawal is being made on behalf of another participant. Null for standard withdrawals.", "example": null }, "sender_participant_code": { "type": "string", "nullable": true, "description": "The participant code of the sender when the request was initiated on behalf of a third party. Null for standard withdrawals.", "example": null }, "requestor_participant_code": { "type": "string", "description": "The participant code of the platform or participant that initiated the request, e.g. ABCDEF.", "example": "ABCDEF" }, "requested_amount": { "type": "string", "description": "The initially requested amount, e.g. 100.10.", "example": "0.1004142" }, "settled_amount": { "type": "string", "nullable": true, "description": "The settled amount. This can be less than or equal to the requested_amount. Null while the withdrawal is still in an APPROVED state.", "example": "0.100414200000000000" }, "status": { "type": "string", "description": "The current status of the withdrawal request.", "enum": [ "PENDING", "APPROVED", "REJECTED", "SETTLED" ], "example": "APPROVED" }, "asset": { "type": "string", "description": "The asset code for the request, e.g. `BTC`.", "enum": [ "AAVE.ETH", "BAT.ETH", "BCH", "BTC", "BUSD", "CEL", "CUSDC", "CVC", "CZRX", "DAI", "ENJ", "EOS", "ETH", "KIN", "KNC", "LINK", "LTC", "OMG", "USDP", "REP", "STORJ", "TUSD", "USDC.ETH", "USDT", "XLM", "XRP", "ZRX" ], "example": "BTC" }, "account_group": { "type": "string", "description": "The account group the request was made against — the platform code of the requesting platform (e.g. `PLAT01`).", "example": "PLAT01" }, "account_label": { "type": "string", "nullable": true, "description": "The account label associated with the account. Null when the request targets the default (unlabeled) account.", "example": null }, "transaction_id": { "type": "string", "nullable": true, "description": "The on-chain transaction hash once the withdrawal has been broadcast. Null until the transaction has been sent to the network.", "example": "0x0c36fd59b0f48257b5cd02cdf23fd8fb8230e27c5ddd28ce02c8a6a4736da4e6" }, "input_data": { "type": "string", "nullable": true, "description": "Applicable only for smart-contract executions on the Ethereum blockchain. The ABI encoding of the function and its arguments in RLP format. Null for standard transfers.", "example": null }, "requested_timestamp": { "type": "number", "format": "int64", "description": "Unix timestamp in milliseconds for when the withdrawal request was last updated. Changes with status updates.", "example": 1777830138534 }, "created_timestamp": { "type": "string", "format": "date-time", "description": "RFC 3339 / ISO 8601 timestamp (UTC) of when the withdrawal request was originally created. Immutable.", "example": "2026-05-03T17:40:10.733Z" }, "gas_price": { "type": "string", "nullable": true, "description": "The transaction fee payable on the Ethereum network. Null when the asset is not an ERC-20 token or when the fee was not client-supplied.", "example": null }, "client_withdrawal_request_id": { "type": "string", "nullable": true, "description": "A unique identifier for the withdrawal, generally produced by the Platform on which the trade was executed. Must be unique per platform per 24-hour period. Null when not provided by the client.", "example": "20aed707-3127-427d-a47e-97efc6470cb3" }, "on_chain_status": { "type": "string", "nullable": true, "description": "Indicates whether the crypto withdrawal has been confirmed on-chain. Null for fiat withdrawals or while the request is still APPROVED and has not been broadcast.", "enum": [ "PENDING", "CONFIRMED", null ], "example": "CONFIRMED" }, "fee_amount": { "type": "string", "nullable": true, "description": "The network fee (denominated in the network fee asset) associated with the withdrawal. Null until the fee has been determined.", "example": "0.000004021417575" }, "withdrawal_fee": { "type": "string", "nullable": true, "description": "The withdrawal fee (denominated in the withdrawn asset) charged by zerohash. Returned as an empty string or null when no withdrawal fee applies.", "example": "0" }, "quoted_fee_amount": { "type": "string", "nullable": true, "description": "The fee paid by the customer in crypto terms as quoted. Null when the withdrawal did not go through the quoted-fee flow.", "example": null }, "quoted_fee_notional": { "type": "string", "nullable": true, "description": "The fee paid by the customer in USD terms as quoted. Null when the withdrawal did not go through the quoted-fee flow.", "example": null }, "quoted_fee_asset": { "type": "string", "nullable": true, "description": "The asset in which the quoted fee was charged. Null when the withdrawal did not go through the quoted-fee flow.", "example": null }, "trade_id": { "type": "string", "nullable": true, "format": "uuid", "description": "When a fee-locked `trade_id` was supplied on the withdrawal request, the associated trade identifier. Null otherwise.", "example": null }, "parent_link_id": { "type": "string", "nullable": true, "description": "Identifier linking this withdrawal to a parent request (for example a convert-and-withdraw quote execution). Null for standalone withdrawals.", "example": null }, "parent_link_id_source": { "type": "string", "nullable": true, "description": "The source context of the `parent_link_id` when present. Null when `parent_link_id` is null.", "example": null }, "amount_in_usd": { "type": "number", "nullable": true, "description": "Indicative USD value of the withdrawal at the time the record was returned. Present on list responses for all consumers; conditionally omitted on single-request responses for non-portal origins.", "example": 234.32708342365032 }, "contract_validation_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Identifier of the EVM smart-contract execution validation record linked to the withdrawal. Null unless the withdrawal targets a validated contract call.", "example": null }, "recipient_instructions": { "type": "string", "nullable": true, "description": "Recipient instructions for this withdrawal request (e.g. wire memo). Returns the request-level memo if provided, otherwise the account default, or null when none is set.", "example": "Invoice #123" } } } } } } ```