--- updatedAt: 2026-08-27T22:50:07.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # List virtual accounts Returns a paginated list of virtual accounts scoped to the authenticated platform. With `participant_code`, returns only that participant's virtual accounts. Without `participant_code`, returns all of the platform's virtual accounts across every participant. Filterable by `status` and `currency`. # 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 }, "paths": { "/virtual_accounts": { "get": { "tags": [ "Virtual Accounts" ], "summary": "List virtual accounts", "description": "Returns a paginated list of virtual accounts scoped to the authenticated platform. With `participant_code`, returns only that participant's virtual accounts. Without `participant_code`, returns all of the platform's virtual accounts across every participant. Filterable by `status` and `currency`.", "parameters": [ { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/ParticipantCodeQuery" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "ACTIVE", "CLOSING", "CLOSED", "BLOCKED", "FAILED" ] } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USD" ] } } ], "responses": { "200": { "description": "Paginated list of virtual accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountListResponse" } } } }, "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" } }, "PageQuery": { "name": "page", "in": "query", "description": "Page number for pagination (starts at 1).", "required": false, "schema": { "type": "number", "minimum": 1, "example": 1 } }, "PageSizeQuery": { "name": "page_size", "in": "query", "description": "Number of items per page for pagination. Default and maximum is 100", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 100, "example": 15 } }, "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": { "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" } } }, "VirtualAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The virtual account identifier, equal to the `Idempotency-Key` supplied on creation.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "participant_code": { "type": "string", "example": "PART01" }, "platform_code": { "type": "string", "example": "PLAT01" }, "provider_type": { "type": "string", "enum": [ "CRB" ], "nullable": true, "description": "Banking partner backing the account.", "example": "CRB" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "CLOSING", "CLOSED", "BLOCKED", "FAILED" ], "nullable": true, "description": "Lifecycle state. `PENDING` until the banking partner issues the account; `FAILED` when the banking partner declined to onboard the customer; `CLOSED`, `BLOCKED` and `FAILED` are terminal.", "example": "PENDING" }, "currency": { "type": "string", "enum": [ "USD" ], "example": "USD" }, "virtual_account_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Platform-supplied label for the account, set at creation and immutable afterwards. When supplied it is used verbatim as the title on the banking partner’s own record of the account. `null` when it was not supplied.", "example": "Acme Holdings Operating Account" }, "named_account": { "type": "boolean", "description": "Echoed back exactly as supplied at creation. Reserved for a future named-account feature; it drives no behaviour today, so do not branch on it.", "example": false }, "account_label": { "type": "string", "maxLength": 40, "description": "Label of the account deposits into this virtual account are credited to, set at creation and immutable afterwards. `general` when none was supplied.", "example": "treasury" }, "bank_details": { "$ref": "#/components/schemas/BankDetails" }, "status_detail": { "$ref": "#/components/schemas/StatusDetail" }, "settlement_policy": { "$ref": "#/components/schemas/SettlementPolicy" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-20T14:22:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-20T14:22:00.000Z" } } }, "VirtualAccountListResponse": { "type": "object", "properties": { "message": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualAccount" } }, "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 200 }, "total_pages": { "type": "integer", "example": 1 }, "count": { "type": "integer", "example": 1 } } }, "BankDetails": { "type": "object", "nullable": true, "description": "Deposit instructions for the virtual account. Present only when `status` is `ACTIVE`, `CLOSING`, `CLOSED` or `BLOCKED`; `null` while the account is `PENDING`, when the banking partner has not yet issued the account, and always for `FAILED`.", "properties": { "bank_account_number": { "type": "string", "example": "0000000001" }, "bank_routing_number": { "type": "string", "example": "123456789" }, "provider_account_id": { "type": "string", "description": "The banking partner's own identifier for the account.", "example": "0000000001" }, "bank_name": { "type": "string", "example": "Cross River Bank" } } }, "StatusDetail": { "type": "object", "nullable": true, "description": "Supplementary context for a terminal failure. Populated when `status` is `FAILED` or `BLOCKED`; `null` otherwise. `code` is drawn from a closed, additive set — treat any value not listed in `enum` as a terminal, unclassified failure.", "properties": { "code": { "type": "string", "enum": [ "VA_CREATION_DECLINED", "VA_CREATION_FAILED", "VA_BLOCKED" ], "example": "VA_CREATION_FAILED" }, "message": { "type": "string", "example": "zerohash was unable to open this virtual account. Contact zerohash support to request a new account." }, "at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-21T09:05:00.000Z" } } }, "SettlementPolicy": { "nullable": true, "description": "Determines what happens to money once it lands in the virtual account. Discriminated union on `type` with two variants:\n- **`HOLD`** — dollars in, dollars held. The USD you send settles as a USD balance in the virtual account.\n- **`AUTO_CONVERT_AND_WITHDRAW`** — the incoming USD is converted into the selected `asset` and sent to the `external_account_id` previously linked to the participant.\n\nRequired at creation; there is no implicit default. May be `null` in responses for accounts created before settlement policies were introduced.", "oneOf": [ { "title": "HOLD", "type": "object", "description": "Dollars in, dollars held — the USD you send settles as a USD balance in the virtual account.", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "HOLD" ], "example": "HOLD" } } }, { "title": "AUTO_CONVERT_AND_WITHDRAW", "type": "object", "description": "Incoming USD is automatically converted into the selected `asset` and sent to the `external_account_id` previously linked to the participant. Both fields are required.", "required": [ "type", "asset", "external_account_id" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "AUTO_CONVERT_AND_WITHDRAW" ], "example": "AUTO_CONVERT_AND_WITHDRAW" }, "asset": { "type": "string", "minLength": 1, "description": "Crypto asset the USD balance is converted into before withdrawal.", "example": "USDC" }, "external_account_id": { "type": "string", "format": "uuid", "description": "External crypto account the converted funds are sent to. Must already be linked to the participant.", "example": "550e8400-e29b-41d4-a716-446655440000" } } } ] } } } } ```