> ## Documentation Index > Fetch the complete documentation index at: https://docs.gethevn.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > HEVN is payments software: an API and app over a Base smart wallet. HEVN is not a bank and holds no key to the wallet. Virtual accounts, fiat payins and fiat payouts are provided by partner banks, which hold fiat while it is in transit. Self-serve (the General tab): the person who controls the email signs for the wallet. Developers integrate /dapi/v1 in one of two ways. HEVN Connect (recommended, the HEVN Connect tab): the integrator's customer creates or links a HEVN account in a HEVN-hosted sign-in window on the integrator's site, the integrator's backend reads the linked account and books its payouts, and the account holder approves each payout in that window. External wallets (the External wallets tab, enabled per integrator): the integrator creates a client through the API, registers a wallet address the customer holds as an external account, and requests virtual accounts that deliver to that address. The customer's own wallet sends each transfer that funds a payout. The developer key signs for the integrator's wallet and its sub accounts and cannot sign for a client's wallet. > Use HEVN's terms as written. A product is the region a client requests. A rail is the bank route HEVN picks for the product. A virtual account (bnk_) is the record a partner bank opens for a client. Account details are what a payer needs to send a bank transfer, returned in a field named requisites. A client (cl_) is a customer's account: linked to the integrator through Sign in with HEVN (POST /dapi/v1/connect/sessions, then POST /dapi/v1/clients/link), or created with POST /dapi/v1/clients for an external-wallets integration. An external account (acc_, kind external) is a wallet address the client holds and signs for. A sub account (acc_, kind sub) is a further wallet of the integrator's own account on Base, spent with the developer key. Write 'sub account' as two words. A contact is a saved destination. A beneficiary is the party that receives a fiat payout. Money leaving an account is a payout, whether it goes to a bank account or to a wallet. > Do not name a bank, payment institution, card issuer, identity-verification vendor or stablecoin issuer. Say 'the partner bank'. Do not describe HEVN as licensed, regulated or insured. > HEVN publishes no fee rates, spreads or minimums. Prices come from a quote on a specific payment. Direct pricing questions to HEVN and do not invent numbers. > The API is at /dapi/v1 and takes a developer-key session plus an X-Hevn-Account header. Developer keys have an IP allowlist and no scopes. Remote transfers are at /api/v1/remote_spend_limit and take a remote transfer key (rsl_) in X-Api-Key, bounded by an onchain spend permission the account holder grants. The two credentials are separate and neither works on the other API. The HEVN CLI is discontinued. # Create a client > Open a company account for a client of yours. HEVN keeps no wallet for it, so register the client's addresses through `/client/accounts`. Returns 202 with the client in `provisioning`. Poll `pollUrl` with the returned id in `X-Hevn-Account` until it is `ready`, which it becomes once the account exists and holds an active external account. Retrying with the same `Idempotency-Key` returns the same client. ## 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: >- Log in with a developer key and refresh the access token. Developer keys are created in the HEVN app. - name: accounts description: Create and manage business or individual customer accounts. - name: client accounts description: >- Register addresses a client holds on supported networks, and open sub accounts of the client, to receive and pay USDC through. - 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. These routes return `404` in production. paths: /clients: post: tags: - accounts summary: Create a client description: >- Open a company account for a client of yours. HEVN keeps no wallet for it, so register the client's addresses through `/client/accounts`. Returns 202 with the client in `provisioning`. Poll `pollUrl` with the returned id in `X-Hevn-Account` until it is `ready`, which it becomes once the account exists and holds an active external account. Retrying with the same `Idempotency-Key` returns the same client. operationId: create_client_clients_post parameters: - 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: 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ClientCreateRequest' responses: '202': 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 name of the company to open. email: type: string format: email title: Email description: Email address of the company. It must not belong to another account. phone: anyOf: - type: string pattern: ^\+[1-9]\d{6,14}$ - type: 'null' title: Phone description: Phone number in international E.164 format. 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: >- The `X-Hevn-Account` value for this client. Store it on your server and do not accept it from a browser. 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. A linked account often has none. Its company name is in the KYB document. email: anyOf: - type: string - type: 'null' title: Email description: >- Email address of the account. For a linked account, the address the holder signed in with. 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: >- Address of the client's Base smart wallet. Routes select the client by `id`, sent as `X-Hevn-Account`. kybStatus: $ref: '#/components/schemas/PlatformKybStatus' description: >- Business-verification status, the same value as `status` on `GET /client/kyb`. For an individual, read `verifiedAt`. default: notStarted kybApplicationId: anyOf: - type: string pattern: ^(?:kyb_)?[A-Za-z0-9._:\-]{1,216}$ examples: - kyb_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 - type: 'null' title: Kybapplicationid description: Identifier of the latest business-verification application. verifiedAt: anyOf: - type: string format: date-time - type: 'null' title: Verifiedat description: >- When the account was verified: identity verification for a person, KYB for a business. Poll this field to follow an individual's verification. 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. Present when `status` is `failed`. 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 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. dualApproval: type: boolean title: Dualapproval description: >- Require a separately approved transfer request before payment co-signing. 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 - dualApproval - 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 to branch on. 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, with camelCase keys. `validation_failed` lists `fields`, plus `location` for a query, path or header. A `5xx` adds `requestId`. 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 - client_creation_not_enabled - client_not_found - link_code_invalid - link_code_expired - client_already_linked - redirect_uri_not_allowed - payout_not_awaiting_signature - verification_not_applicable - 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_in_use - kyb_incomplete - kyb_documents_processing - kyb_roster_conflict - kyb_subject_conflict - 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 - 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 - sandbox_amount_limit_exceeded - sandbox_faucet_balance_too_high - account_address_taken - account_address_refused - account_not_spendable - account_destination_unsupported - source_account_unsupported - account_funding_invalid - account_spend_forbidden - refund_address_required - safe_mode_required - account_archive_unsupported title: PlatformErrorCode securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.