> ## 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. # Decide the client's latest KYB application, as the compliance reviewer would > Moves the client's latest application to `approved`, `rfi` or `rejected`, and returns the body of `GET /dapi/v1/client/kyb`. Sending the current status returns it unchanged. For an individual client with no application, `approved` verifies the client. Otherwise a client with no application returns `409 conflict`, and so does an application in `rfi` or `rejected`. Complete the submission again to file a new attempt. ## OpenAPI ````yaml /openapi.json post /sandbox/kyb/status 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: /sandbox/kyb/status: post: tags: - sandbox summary: >- Decide the client's latest KYB application, as the compliance reviewer would description: >- Moves the client's latest application to `approved`, `rfi` or `rejected`, and returns the body of `GET /dapi/v1/client/kyb`. Sending the current status returns it unchanged. For an individual client with no application, `approved` verifies the client. Otherwise a client with no application returns `409 conflict`, and so does an application in `rfi` or `rejected`. Complete the submission again to file a new attempt. operationId: set_kyb_status_sandbox_kyb_status_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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SandboxKybStatusRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PlatformKybResponse' '422': description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/PlatformErrorResponse' security: - HTTPBearer: [] components: schemas: SandboxKybStatusRequest: properties: status: $ref: '#/components/schemas/KybApplicationStatus' description: >- The reviewer's decision: `approved`, `rfi` or `rejected`. `approved` needs a `pending` application, the other two a `pending` or `approved` one. comment: anyOf: - type: string maxLength: 2000 minLength: 1 - type: 'null' title: Comment description: >- What the reviewer tells the client, returned as `application.comment`. Required for `rfi` and `rejected`. additionalProperties: false type: object required: - status title: SandboxKybStatusRequest PlatformKybResponse: properties: ready: type: boolean title: Ready description: True when missing is empty and completion can be attempted. missing: items: type: string type: array title: Missing description: >- Outstanding fields and document slots as paths into the document, for example company.address.zip or people[0].documents.proof_of_address. A people index is the position in document.people of GET /dapi/v1/client/kyb. status: $ref: '#/components/schemas/PlatformKybStatus' description: >- Review status of the latest application. It equals kybStatus on the client record. default: notStarted application: anyOf: - $ref: '#/components/schemas/PlatformKybApplicationResponse' - type: 'null' description: Latest immutable submission under review. document: $ref: '#/components/schemas/PlatformKybDocumentBody' description: >- Current editable verification document projected from the entity graph. type: object required: - ready title: PlatformKybResponse PlatformErrorResponse: properties: error: $ref: '#/components/schemas/PlatformErrorBody' description: Public error body. type: object required: - error title: PlatformErrorResponse KybApplicationStatus: type: string enum: - pending - approved - rfi - rejected - superseded title: KybApplicationStatus PlatformKybStatus: type: string enum: - notStarted - pending - approved - rfi - rejected title: PlatformKybStatus PlatformKybApplicationResponse: properties: id: type: string pattern: ^(?:kyb_)?[A-Za-z0-9._:\-]{1,216}$ title: Id description: Immutable verification application identifier. examples: - kyb_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 attemptNo: type: integer title: Attemptno description: One-based attempt number. It increments with each new application. status: $ref: '#/components/schemas/PlatformKybStatus' description: Current public review status. comment: anyOf: - type: string - type: 'null' title: Comment description: >- Review comment safe to show to the account holder. Each review replaces it. submittedAt: type: string format: date-time title: Submittedat description: UTC timestamp when the immutable submission entered review. decidedAt: anyOf: - type: string format: date-time - type: 'null' title: Decidedat description: UTC timestamp of the latest review decision. type: object required: - id - attemptNo - status - submittedAt title: PlatformKybApplicationResponse PlatformKybDocumentBody: properties: company: anyOf: - $ref: '#/components/schemas/PlatformKybCompanyView' - type: 'null' description: Business-applicant information. people: items: $ref: '#/components/schemas/PlatformKybPersonView' type: array title: People description: Related individual applicants. documents: items: $ref: '#/components/schemas/PlatformKybDocumentView' type: array title: Documents description: Business-level documents. type: object title: PlatformKybDocumentBody 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 PlatformKybCompanyView: properties: legalName: anyOf: - type: string - type: 'null' title: Legalname description: Registered legal name of the business applicant. tradeName: anyOf: - type: string - type: 'null' title: Tradename description: Trading name or DBA, when different from legalName. country: anyOf: - type: string - type: 'null' title: Country description: ISO 3166-1 alpha-2 jurisdiction of incorporation. registrationNumber: anyOf: - type: string - type: 'null' title: Registrationnumber description: Company registry number exactly as issued. linkedinUrl: anyOf: - type: string - type: 'null' title: Linkedinurl description: Public LinkedIn company URL. taxId: anyOf: - type: string - type: 'null' title: Taxid description: Business tax identifier exactly as issued. phone: anyOf: - type: string - type: 'null' title: Phone description: Business phone number in E.164 format. email: anyOf: - type: string - type: 'null' title: Email description: Business contact email used for verification correspondence. address: anyOf: - $ref: '#/components/schemas/PlatformKybAddressView' - type: 'null' description: Registered business address. entityType: anyOf: - type: string - type: 'null' title: Entitytype description: Legal form of the business applicant. entityTypeDescription: anyOf: - type: string - type: 'null' title: Entitytypedescription description: Legal-form detail when entityType is other. incorporationDate: anyOf: - type: string format: date - type: 'null' title: Incorporationdate description: Date the business was legally registered. industry: anyOf: - type: string - type: 'null' title: Industry description: Free-text description of the business industry. websites: anyOf: - items: type: string type: array - type: 'null' title: Websites description: Public business websites, primary site first. operatingCountries: anyOf: - items: type: string type: array - type: 'null' title: Operatingcountries description: ISO country codes where the business operates. expectedMonthlyVolumeUsd: anyOf: - type: string example: '500.00' - type: 'null' title: Expectedmonthlyvolumeusd description: Expected total monthly transaction volume in USD. expectedCryptoMonthlyVolumeUsd: anyOf: - type: string example: '500.00' - type: 'null' title: Expectedcryptomonthlyvolumeusd description: Expected monthly digital-asset transaction volume in USD. expectedMonthlyAchUsd: anyOf: - type: string example: '500.00' - type: 'null' title: Expectedmonthlyachusd description: Expected monthly ACH volume in USD. expectedMonthlyWireUsd: anyOf: - type: string example: '500.00' - type: 'null' title: Expectedmonthlywireusd description: Expected monthly international-transfer volume in USD. cryptoIndustrySubtype: anyOf: - type: string - type: 'null' title: Cryptoindustrysubtype description: Digital-asset business subtype. hasIntermediateEntityOwnership: anyOf: - type: boolean - type: 'null' title: Hasintermediateentityownership description: >- Whether another legal entity exists between the applicant and an ultimate owner. primaryTargetMarket: anyOf: - type: string - type: 'null' title: Primarytargetmarket description: Primary customer segment served by the business. estimatedAnnualRevenue: anyOf: - type: string example: '500.00' - type: 'null' title: Estimatedannualrevenue description: Estimated annual revenue in USD. hasUsBank: anyOf: - type: boolean - type: 'null' title: Hasusbank description: Whether the business holds a US payment account. deniedUsBank: anyOf: - type: boolean - type: 'null' title: Deniedusbank description: >- Whether a US financial institution declined or closed the business account. hasPep: anyOf: - type: boolean - type: 'null' title: Haspep description: Whether a politically exposed person is connected. bizAdverse: anyOf: - items: type: string type: array - type: 'null' title: Bizadverse description: Declared adverse information about the business. ownersAdverse: anyOf: - items: type: string type: array - type: 'null' title: Ownersadverse description: Declared adverse information about owners. publicListed: anyOf: - type: boolean - type: 'null' title: Publiclisted description: Whether the business is publicly listed. txPerMonth: anyOf: - type: string - type: 'null' title: Txpermonth description: Expected number of transactions per month. usesBlockchain: anyOf: - type: boolean - type: 'null' title: Usesblockchain description: Whether digital assets are used in operations. revenueCovers: anyOf: - type: string - type: 'null' title: Revenuecovers description: How much of operating expenses current revenue covers. institutionalInvestors: anyOf: - type: boolean - type: 'null' title: Institutionalinvestors description: Whether institutional investors fund or own it. isRegulated: anyOf: - type: boolean - type: 'null' title: Isregulated description: Whether the business is regulated or licensed. regulatorCountry: anyOf: - type: string - type: 'null' title: Regulatorcountry description: >- ISO 3166-1 alpha-2 country of the authority that licenses the business. regulatoryLicenseType: anyOf: - type: string - type: 'null' title: Regulatorylicensetype description: Type of regulatory license the business holds. verifiesCustomerIdentity: anyOf: - type: boolean - type: 'null' title: Verifiescustomeridentity description: Whether the business verifies the identity of its own customers. hasTransactionMonitoring: anyOf: - type: boolean - type: 'null' title: Hastransactionmonitoring description: Whether the business monitors its customers' transactions. productsServices: anyOf: - items: type: string type: array - type: 'null' title: Productsservices description: Products and services offered by the business. businessDescription: anyOf: - type: string - type: 'null' title: Businessdescription description: Plain-language description of what the business does. businessType: anyOf: - type: string - type: 'null' title: Businesstype description: High-level business activity category. businessIndustry: anyOf: - type: string - type: 'null' title: Businessindustry description: Industry classification used for verification. verifierRole: anyOf: - type: string - type: 'null' title: Verifierrole description: Role of the person providing verification information. sourceOfFunds: anyOf: - type: string - type: 'null' title: Sourceoffunds description: Primary economic source of incoming funds. sourceOfFundsDetails: anyOf: - type: string - type: 'null' title: Sourceoffundsdetails description: Additional source-of-funds explanation. purposeOfFunds: anyOf: - type: string - type: 'null' title: Purposeoffunds description: Primary intended use of funds. purposeOfFundsDetails: anyOf: - type: string - type: 'null' title: Purposeoffundsdetails description: Additional purpose-of-funds explanation. flowOfFunds: anyOf: - type: string - type: 'null' title: Flowoffunds description: Expected origin, movement and destination of funds. complianceScreening: anyOf: - type: string - type: 'null' title: Compliancescreening description: How customers and transactions are screened. moneyServicesDescription: anyOf: - type: string - type: 'null' title: Moneyservicesdescription description: Description of money-services activity. handlesCustomerFunds: anyOf: - type: boolean - type: 'null' title: Handlescustomerfunds description: Whether customer funds are handled. actingAsIntermediary: anyOf: - type: boolean - type: 'null' title: Actingasintermediary description: Whether the business acts as a payment intermediary. sanctionedCountryOperations: anyOf: - type: boolean - type: 'null' title: Sanctionedcountryoperations description: Whether the business operates in or serves sanctioned jurisdictions. highRiskActivities: anyOf: - items: type: string type: array - type: 'null' title: Highriskactivities description: Declared higher-risk business activities. depositMethods: anyOf: - items: type: string type: array - type: 'null' title: Depositmethods description: Expected methods or regions used to fund the account. contactInfo: anyOf: - type: string - type: 'null' title: Contactinfo description: Additional business contact or operational information. identityDocuments: items: $ref: '#/components/schemas/PlatformKybIdentityDocumentView' type: array title: Identitydocuments description: Structured identity-document metadata for the business. type: object title: PlatformKybCompanyView PlatformKybPersonView: properties: key: anyOf: - type: string - type: 'null' title: Key description: >- Caller-chosen stable key. Null for a person added outside this route. id: type: string format: uuid title: Id description: Entity identifier assigned to the related applicant. firstName: anyOf: - type: string - type: 'null' title: Firstname description: Applicant's legal given name. middleName: anyOf: - type: string - type: 'null' title: Middlename description: Applicant's legal middle name, if any. lastName: anyOf: - type: string - type: 'null' title: Lastname description: Applicant's legal family name. dateOfBirth: anyOf: - type: string format: date - type: 'null' title: Dateofbirth description: Applicant's date of birth. birthCountry: anyOf: - type: string - type: 'null' title: Birthcountry description: ISO country code of birth. nationalities: anyOf: - items: type: string type: array - type: 'null' title: Nationalities description: Applicant nationalities as ISO country codes. title: anyOf: - type: string - type: 'null' title: Title description: Office held in the business. country: anyOf: - type: string - type: 'null' title: Country description: ISO country code of residence. linkedinUrl: anyOf: - type: string - type: 'null' title: Linkedinurl description: Public LinkedIn profile URL. email: anyOf: - type: string - type: 'null' title: Email description: Applicant email used for verification correspondence. phone: anyOf: - type: string - type: 'null' title: Phone description: Applicant phone number in E.164 format. address: anyOf: - $ref: '#/components/schemas/PlatformKybAddressView' - type: 'null' description: Applicant residential address. taxIdCountry: anyOf: - type: string - type: 'null' title: Taxidcountry description: ISO country code of tax residence. taxId: anyOf: - type: string - type: 'null' title: Taxid description: Personal tax identifier exactly as issued. identityDocuments: items: $ref: '#/components/schemas/PlatformKybIdentityDocumentView' type: array title: Identitydocuments description: Identity-document metadata for this applicant. ownershipPercentage: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Ownershippercentage description: Direct ownership percentage. hasControl: type: boolean title: Hascontrol description: Whether this applicant exercises control. default: false isDirector: type: boolean title: Isdirector description: Whether this applicant is a director. default: false isSigner: type: boolean title: Issigner description: Whether this applicant is authorized to sign. default: false documents: items: $ref: '#/components/schemas/PlatformKybDocumentView' type: array title: Documents description: Files attached to this related applicant. type: object required: - id title: PlatformKybPersonView PlatformKybDocumentView: properties: slot: $ref: '#/components/schemas/DocumentType' description: Verification requirement this file satisfies. uploadId: type: string pattern: ^(?:doc_)?[A-Za-z0-9._:\-]{1,216}$ title: Uploadid description: Document identifier returned by POST /dapi/v1/documents. examples: - doc_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 type: object required: - slot - uploadId title: PlatformKybDocumentView 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 PlatformKybAddressView: properties: streetAddress: anyOf: - type: string - type: 'null' title: Streetaddress description: Street name and building number. addressLine2: anyOf: - type: string - type: 'null' title: Addressline2 description: Optional apartment, suite or unit. city: anyOf: - type: string - type: 'null' title: City description: City or locality. state: anyOf: - type: string - type: 'null' title: State description: State, province or administrative area. zip: anyOf: - type: string - type: 'null' title: Zip description: Postal or ZIP code. country: anyOf: - type: string - type: 'null' title: Country description: ISO 3166-1 alpha-2 country code. type: object title: PlatformKybAddressView PlatformKybIdentityDocumentView: properties: type: anyOf: - $ref: '#/components/schemas/FiatIdentityDocumentType' - type: 'null' description: Identity document type. issuingCountry: anyOf: - type: string - type: 'null' title: Issuingcountry description: ISO country code of the issuing authority. number: anyOf: - type: string - type: 'null' title: Number description: Document number exactly as printed by the issuer. type: object title: PlatformKybIdentityDocumentView DocumentType: type: string enum: - certificate_of_incorporation - certificate_of_registration - formation_document - articles_of_incorporation - power_of_attorney - corporate_structure - org_structure_chart - company_registry_extract - corporate_registry_extract - shareholder_registry - cap_table - director_structure - proof_of_address - utility_bill - aml_policy - annual_financial_statements - articles_of_association - audit_report - independent_aml_audit_report - identity_verification_attestation - institutional_investor_documentation - audited_financial_statement - bank_reference_letter - bank_verification_letter - bank_statement - banking_details - birth_certificate - business_license - operating_license - business_plan - certificate_of_good_standing - corporate_resolution - proof_of_registered_address - proof_of_operating_address - crypto_statement - credit_report - criminal_record_check - cv_resume - driving_license - education_certificate - financial_projections - investment_statement - insurance_policy - lease_agreement - marriage_certificate - national_id - national_id_front - national_id_back - operating_agreement - partnership_agreement - professional_license - regulatory_license - reference_letter - register_of_members - residence_permit - shareholding_structure - shareholders_agreement - social_security_document - source_of_funds_declaration - tax_identification_document - ein_letter - tax_certificate - tax_compliance_form - tax_returns - payslip - pitch_deck - savings_statement - trade_references - vat_registration - vendor_contracts - visa - wealth_statement - contract - invoice - loan_agreement - subscription_agreement - safe_agreement - convertible_note - promissory_note - marketing_material - employment_contract - authorization_to_act - authority_to_bind - ubo_declaration - income_verification_letter - source_of_funds - flow_of_funds - payroll_register - investment_agreement - source_of_wealth - supporting_document - memorandum - passport_front - passport_back - id_card_front - id_card_back - drivers_license_front - drivers_license_back - residence_permit_front - residence_permit_back - other title: DocumentType FiatIdentityDocumentType: type: string enum: - passport - id_card - drivers_license - driver_license - residence_permit - government_id - state_or_provincial_id - visa title: FiatIdentityDocumentType description: Identity document type. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.