> ## Documentation Index > Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > HEVN has two products and they authorize money differently. Self-serve (the General tab): the person who owns the email holds the only key and signs for themselves. Whitelabel (the Whitelabel and REST API tabs): the integrator's backend holds a developer key, signs on behalf of client accounts it created, and HEVN co-signs. Never mix the two models in an answer. > Use HEVN's terms exactly. A rail is a bank route a client can request. A virtual account (bnk_) is an opened rail. Account details are what a payer needs in order to wire money, and arrive in a field named requisites. A client is an account the integrator created; the business behind it is the integrator's customer. A contact is a saved destination; a beneficiary is the party at the far end of a fiat payout. Every departure of money is a payout, to a bank account or to a wallet alike. > Never name a banking partner. Say 'a licensed banking partner'. > There are no published fee rates, spreads or minimums. Prices come from a quote on a specific payment; direct pricing questions to HEVN rather than inventing numbers. > The whitelabel API is at /dapi/v1 and takes a developer-key session plus an X-Hevn-Account header. The CLI uses an app API key in X-Api-Key. They are different credentials and neither works on the other surface. # Create a client > Provision a company account for one of your clients. The id is knowable at once, so poll `pollUrl` with the returned `id` in `X-Hevn-Account` until `status` is `ready` — about 30 seconds. An identical resubmit answers 200 with `Idempotency-Replayed: true` and the same id. Developer-role callers may set `transferPolicy`; otherwise all allow flags default to true and both security-state flags default to false. ## OpenAPI ````yaml /openapi.json post /clients openapi: 3.1.0 info: title: HEVN Platform API description: >- HEVN's account, verification and money-movement API. Verification follows a submission workflow: save applicant info and documents, inspect outstanding requirements, then explicitly complete the submission to send an immutable snapshot for review. Completing a submission is separate from editing it. version: 1.0.0 servers: [] security: [] tags: - name: auth description: Authenticate an integration and issue short-lived account sessions. - name: accounts description: Create and manage business or individual customer accounts. - name: verification description: >- Collect business-applicant and related-individual information, inspect requirements, and complete a verification submission for review. - name: documents description: Upload verification and payment evidence for later reference by id. - name: virtual accounts description: Discover payment methods and create persistent receiving account details. - name: transfers description: Quote, create, authorize and track incoming or outgoing transfers. - name: contacts description: Create saved contacts and inspect their available payment channels. - name: transactions description: Read and export the account ledger. - name: escrow description: Create, authorize and reconcile on-chain escrow agreements. - name: sandbox description: Emulate funding and lifecycle events in the sandbox environment. paths: /clients: post: tags: - accounts summary: Create a client description: >- Provision a company account for one of your clients. The id is knowable at once, so poll `pollUrl` with the returned `id` in `X-Hevn-Account` until `status` is `ready` — about 30 seconds. An identical resubmit answers 200 with `Idempotency-Replayed: true` and the same id. Developer-role callers may set `transferPolicy`; otherwise all allow flags default to true and both security-state flags default to false. operationId: create_client_clients_post parameters: - name: Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Your own key for this write, `^[A-Za-z0-9._:-]{1,128}$`. A retry with the same key replays the first answer; the same key with a different request is refused. examples: - po-inv-2026-114 title: Idempotency-Key description: >- Your own key for this write, `^[A-Za-z0-9._:-]{1,128}$`. A retry with the same key replays the first answer; the same key with a different request is refused. - name: X-Hevn-Account in: header required: false schema: anyOf: - type: string - type: 'null' description: >- The client account to act for, as a `cl_…` id. Omit it to act as yourself. examples: - cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 title: X-Hevn-Account description: >- The client account to act for, as a `cl_…` id. Omit it to act as yourself. - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ClientCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ClientResponse' '422': description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/PlatformErrorResponse' security: - HTTPBearer: [] components: schemas: ClientCreateRequest: properties: name: type: string maxLength: 500 minLength: 1 title: Name description: Legal or trading name used to identify the account. email: type: string format: email title: Email description: Unique account email used for verification correspondence. phone: anyOf: - type: string pattern: ^\+[1-9]\d{6,14}$ - type: 'null' title: Phone description: Phone number in international E.164 format. transferPolicy: anyOf: - $ref: '#/components/schemas/InitialTransferPolicy' - type: 'null' description: >- Initial account transfer controls, available only to developer-role callers. When omitted, every allow flag is true while isFrozen and recoveryModeActivated are false. additionalProperties: false type: object required: - name - email title: ClientCreateRequest ClientResponse: properties: id: type: string pattern: ^(?:cl_)?[A-Za-z0-9._:\-]{1,216}$ title: Id description: Stable public identifier for this account. examples: - cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 status: $ref: '#/components/schemas/PlatformClientStatus' description: Current account-provisioning status. name: anyOf: - type: string - type: 'null' title: Name description: Legal or trading name of the account. email: anyOf: - type: string - type: 'null' title: Email description: Email address associated with the account. phone: anyOf: - type: string - type: 'null' title: Phone description: Phone number in international E.164 format. baseSmartWallet: anyOf: - type: string - type: 'null' title: Basesmartwallet description: Base smart-wallet address controlled by the account. kybStatus: $ref: '#/components/schemas/PlatformKybStatus' description: Current business-verification status. default: notStarted kybApplicationId: anyOf: - type: string pattern: ^(?:kyb_)?[A-Za-z0-9._:\-]{1,216}$ examples: - kyb_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 - type: 'null' title: Kybapplicationid description: Latest immutable business-verification application identifier. createdAt: type: string format: date-time title: Createdat description: UTC timestamp when the account was created. failure: anyOf: - $ref: '#/components/schemas/ClientFailureResponse' - type: 'null' description: Provisioning failure details, when present. pollUrl: anyOf: - type: string - type: 'null' title: Pollurl description: >- Relative API URL to poll with this response's id in `X-Hevn-Account`. transferPolicy: anyOf: - $ref: '#/components/schemas/TransferPolicyResponse' - type: 'null' description: Account-level controls for the ways this client may move money. type: object required: - id - status - createdAt title: ClientResponse PlatformErrorResponse: properties: error: $ref: '#/components/schemas/PlatformErrorBody' description: Public error body. type: object required: - error title: PlatformErrorResponse InitialTransferPolicy: properties: allowFiat: type: boolean title: Allowfiat description: >- Allow account-initiated fiat payouts, subject to freeze and recovery controls. default: true allowCrypto: type: boolean title: Allowcrypto description: >- Allow account-initiated on-chain transfers, including transfers to another platform account, subject to freeze and recovery controls. default: true allowThirdParty: type: boolean title: Allowthirdparty description: >- Allow fiat or on-chain payouts to an external contact. Email and escrow payments within the same platform group use narrower controls. default: true allowEscrowThirdParty: type: boolean title: Allowescrowthirdparty description: >- Allow escrow to another platform account. This control is independent from allowThirdParty; same-group escrow also requires allowPartnerGroupPayments. default: true allowSwap: type: boolean title: Allowswap description: Allow balance swaps, subject to freeze and recovery controls. default: true allowPartnerGroupPayments: type: boolean title: Allowpartnergrouppayments description: >- Allow email and escrow payments between accounts in the same platform group. Email payments also require allowCrypto; escrow also requires allowEscrowThirdParty. default: true isFrozen: type: boolean title: Isfrozen description: >- Block every new account-initiated money movement, overriding every allow flag. default: false recoveryModeActivated: type: boolean title: Recoverymodeactivated description: >- Restrict money movement to first-party fiat payouts whose Contact belongs to this account and whose account-holder name matches the account name. default: false additionalProperties: false type: object title: InitialTransferPolicy description: >- Initial money-movement controls accepted only from a developer-role client creator. ``isFrozen`` overrides every permission. When the account is not frozen, ``recoveryModeActivated`` restricts it to first-party fiat withdrawals. The remaining flags are then evaluated for the requested operation. PlatformClientStatus: type: string enum: - provisioning - ready - failed title: PlatformClientStatus PlatformKybStatus: type: string enum: - notStarted - pending - approved - rfi - rejected title: PlatformKybStatus ClientFailureResponse: properties: code: $ref: '#/components/schemas/PlatformClientFailure' description: Stable machine-readable code for the provisioning failure. message: type: string title: Message description: Human-readable explanation safe to show to the account holder. retriable: type: boolean title: Retriable description: Whether retrying later without changing the request may succeed. default: false type: object required: - code - message title: ClientFailureResponse TransferPolicyResponse: properties: allowFiat: type: boolean title: Allowfiat description: >- Allow account-initiated fiat payouts, subject to freeze and recovery controls. allowCrypto: type: boolean title: Allowcrypto description: >- Allow account-initiated on-chain transfers, including transfers to another platform account, subject to freeze and recovery controls. allowThirdParty: type: boolean title: Allowthirdparty description: >- Allow fiat or on-chain payouts to an external contact. Email and escrow payments within the same platform group use narrower controls. allowEscrowThirdParty: type: boolean title: Allowescrowthirdparty description: >- Allow escrow to another platform account. This control is independent from allowThirdParty; same-group escrow also requires allowPartnerGroupPayments. allowSwap: type: boolean title: Allowswap description: Allow balance swaps, subject to freeze and recovery controls. allowPartnerGroupPayments: type: boolean title: Allowpartnergrouppayments description: >- Allow email and escrow payments between accounts in the same platform group. Email payments also require allowCrypto; escrow also requires allowEscrowThirdParty. isFrozen: type: boolean title: Isfrozen description: Block every new money movement, overriding every allow flag. recoveryModeActivated: type: boolean title: Recoverymodeactivated description: >- Restrict money movement to first-party fiat payouts whose Contact belongs to this account and whose account-holder name matches the account name. type: object required: - allowFiat - allowCrypto - allowThirdParty - allowEscrowThirdParty - allowSwap - allowPartnerGroupPayments - isFrozen - recoveryModeActivated title: TransferPolicyResponse description: |- Effective account-level money-movement controls. ``isFrozen`` overrides every permission. When the account is not frozen, ``recoveryModeActivated`` restricts it to first-party fiat withdrawals. The remaining flags are then evaluated for the requested operation. PlatformErrorBody: properties: code: $ref: '#/components/schemas/PlatformErrorCode' description: Stable machine-readable error code. message: type: string title: Message description: Human-readable explanation safe to show to an end user. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Structured context for this error, when available. type: object required: - code - message title: PlatformErrorBody PlatformClientFailure: type: string enum: - provisioning_failed - request_rejected - request_canceled title: PlatformClientFailure PlatformErrorCode: type: string enum: - invalid_request - validation_failed - invalid_cursor - invalid_id - idempotency_key_invalid - idempotency_key_reused - unauthenticated - token_expired - forbidden - not_found - method_not_allowed - conflict - gone - payload_too_large - rate_limited - provider_unavailable - database_unavailable - internal_error - invalid_credentials - request_expired - challenge_not_found - challenge_consumed - challenge_expired - signature_invalid - key_not_registered - signer_not_attached - wallet_not_linked - approval_consumed - approval_expired - approval_mismatch - signing_policy_refused - login_unavailable - login_mode_unavailable - developer_key_not_found - developer_key_already_exists - account_header_invalid - account_scope_conflict - account_not_found - account_forbidden - account_read_only - account_not_controlled - contact_not_found - quote_not_submitted - quote_not_fundable - funding_mode_unsupported - funding_token_unsupported - insufficient_funds - smart_wallet_not_deployed - wallet_owner_unverified - already_funded - payment_slot_consumed - funding_in_progress - funding_attempt_expired - contact_changed - user_operation_rejected - user_operation_unavailable - transfer_policy_denied - integrator_inactive - client_creation_not_enabled - client_policy_not_enabled - email_in_use - name_in_use - client_request_conflict - client_not_found - profile_locked - contact_not_payable - contact_chain_unsupported - contact_token_unsupported - contact_payment_details_invalid - amount_below_minimum - amount_above_maximum - amount_precision_unsupported - payout_not_found - payout_not_fundable - quote_expired - bundler_rejected - bundler_unavailable - contact_details_invalid - contact_in_use - kyb_incomplete - kyb_roster_conflict - kyb_subject_conflict - document_fields_missing - document_not_found - document_type_unsupported - invalid_enum_value - entity_not_found - escrow_not_found - escrow_action_not_found - escrow_not_operated_by_you - escrow_state_changed - action_in_flight - simulation_failed - stale_nonce - amount_out_of_range - amount_not_allowed - window_closed - token_not_supported - receiver_not_a_client - rail_not_found - rail_not_available - rail_requirements_unmet - phone_required - payin_not_available - payin_expired - payin_not_found - transaction_not_found - account_unavailable - account_not_supported - swap_not_found - swap_route_unavailable - swap_not_confirmable - intent_not_signable title: PlatformErrorCode securitySchemes: HTTPBearer: type: http scheme: bearer ````