> ## 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. # Reconcile one escrow with the chain > Reconcile one escrow with current on-chain state. This read-through operation may persist newly observed events but never invents a successful chain action. ## OpenAPI ````yaml /openapi.json post /escrow/{escrowId}/sync openapi: 3.1.0 info: title: HEVN Platform API description: >- One API for integrators. Create client accounts, submit them for verification, open virtual account rails, receive and send money, operate on-chain escrow deals, and read balances and transactions. The base URL already carries the version — every path below is relative to it. Bodies, responses and query parameters are camelCase, null fields are omitted, and every amount is a decimal string in the asset's major unit (`"500.00"`), never a JSON number. Log in with your developer key: `POST /auth/challenge` returns a payload to sign, `POST /auth/token` exchanges the signature for an access token. Send it as `Authorization: Bearer `. The session it mints is platform-only — it reaches `/dapi/v1` and nothing else, and the ordinary `/api/v1` surface refuses it. Registering the key itself, with the source IPs it may be used from, happens on `/api/v1/developer/api-keys` with an ordinary owner session and is deliberately absent from this document. One token is enough for your whole book: name the client you are acting for with `X-Hevn-Account: cl_…`. The singular `/client*` operations require that header; `/clients` and `/escrow*` are about you rather than a client and refuse it. Ids are opaque and prefixed by what they name (`cl_` client, `ct_` contact, `bnk_` rail, `po_` payout, `pi_` payin, `txn_` transaction, `doc_` document, `kyb_` application, `esc_` escrow deal). Never parse one. Every write accepts `Idempotency-Key: <^[A-Za-z0-9._:-]{1,128}$>` and requires none. A retry with the same key replays the first answer and carries `Idempotency-Replayed: true`; the same key with a different request is refused with `idempotency_key_reused`. Lists page with `limit` (default 50, max 100) and the opaque `nextCursor` of the previous page. Every refusal is the same envelope: `{"error": {"code": string, "message": string, "details"?: object}}`. Branch on `error.code`; every slug is listed in the guide's [Errors reference](https://docs.hevn.finance/whitelabel/reference/errors). `unauthenticated` (401), `forbidden` (403), `rate_limited` (429), `validation_failed` (422) and `internal_error` (500) can answer any operation and are not repeated per operation. This document is served by the API itself at `/dapi/v1/openapi.json`, and browsable at `/dapi/v1/docs`. version: 1.0.0 servers: - url: https://api.hevn.finance/dapi/v1 description: Production. Tokens issued here work only here. - url: https://sandbox-api.hevn.finance/dapi/v1 description: Sandbox (Base Sepolia test funds). Tokens issued here work only here. security: - HTTPBearer: [] 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: /escrow/{escrowId}/sync: post: tags: - escrow summary: Reconcile one escrow with the chain description: >- Reconcile one escrow with current on-chain state. This read-through operation may persist newly observed events but never invents a successful chain action. operationId: sync_escrow_escrow__escrowId__sync_post parameters: - name: escrowId in: path required: true schema: type: string pattern: ^(?:esc_)?[A-Za-z0-9._:\-]{1,216}$ title: Escrowid - 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 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EscrowView' '422': description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/PlatformErrorResponse' security: - HTTPBearer: [] components: schemas: EscrowView: properties: id: type: string title: Id description: Stable public identifier for this escrow. status: $ref: '#/components/schemas/PlatformEscrowStatus' description: Current public lifecycle status of the escrow. availableActions: items: $ref: '#/components/schemas/EscrowAction' type: array title: Availableactions description: Actions permitted by current state and deadlines. sender: $ref: '#/components/schemas/EscrowPartyView' description: Account sending or authorizing escrow funds. receiver: $ref: '#/components/schemas/EscrowPartyView' description: Account entitled to captured escrow funds. token: type: string title: Token description: Digital asset held in escrow. maxAmount: type: string title: Maxamount description: Maximum token amount that may be authorized. example: '500.00' authorizedAmount: type: string title: Authorizedamount description: Token amount currently authorized for capture. example: '500.00' capturableAmount: type: string title: Capturableamount description: Token amount that may currently be captured. example: '500.00' refundableAmount: type: string title: Refundableamount description: Token amount that may currently be refunded. example: '500.00' windows: $ref: '#/components/schemas/EscrowWindowsView' description: Approval, holding and refund deadlines. action: anyOf: - $ref: '#/components/schemas/EscrowActionView' - type: 'null' description: Latest prepared or submitted escrow action. consistent: anyOf: - type: boolean - type: 'null' title: Consistent description: Whether persisted state matches the latest chain state. createdAt: type: string format: date-time title: Createdat description: UTC timestamp when the escrow was created. updatedAt: type: string format: date-time title: Updatedat description: UTC timestamp when the escrow was last updated. type: object required: - id - status - availableActions - sender - receiver - token - maxAmount - authorizedAmount - capturableAmount - refundableAmount - windows - createdAt - updatedAt title: EscrowView PlatformErrorResponse: properties: error: $ref: '#/components/schemas/PlatformErrorBody' description: Public error body. type: object required: - error title: PlatformErrorResponse PlatformEscrowStatus: type: string enum: - draft - authorized - charged - partiallyCaptured - captured - voided - reclaimed - partiallyRefunded - refunded title: PlatformEscrowStatus EscrowAction: type: string enum: - approve - authorize - charge - capture - reject - void - reclaim - refund title: EscrowAction EscrowPartyView: properties: clientId: type: string title: Clientid description: Account represented by this escrow party. type: object required: - clientId title: EscrowPartyView EscrowWindowsView: properties: approveBy: type: string format: date-time title: Approveby description: UTC deadline for escrow approval. holdUntil: type: string format: date-time title: Holduntil description: UTC timestamp until which captured funds remain held. refundableUntil: type: string format: date-time title: Refundableuntil description: UTC deadline for a refund. type: object required: - approveBy - holdUntil - refundableUntil title: EscrowWindowsView EscrowActionView: properties: action: $ref: '#/components/schemas/EscrowAction' description: Escrow action represented by this resource. idempotencyKey: type: string title: Idempotencykey description: Key that binds retries to the prepared action. status: $ref: '#/components/schemas/PlatformEscrowActionStatus' description: Current public lifecycle status of the action. amount: anyOf: - type: string example: '500.00' - type: 'null' title: Amount description: Token amount affected by the action. feeBps: anyOf: - type: integer - type: 'null' title: Feebps description: Variable fee in basis points, when charged. transactionHash: anyOf: - type: string - type: 'null' title: Transactionhash description: On-chain transaction hash, when broadcast. approval: anyOf: - $ref: '#/components/schemas/EscrowApprovalView' - type: 'null' description: Authorization to sign before execution. type: object required: - action - idempotencyKey - status title: EscrowActionView 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 PlatformEscrowActionStatus: type: string enum: - awaitingSignature - signing - submitted - confirmed - reverted - failed - superseded - dropped title: PlatformEscrowActionStatus EscrowApprovalView: properties: id: type: string format: uuid title: Id description: Single-use approval identifier. payload: type: string title: Payload description: >- Base64 canonical authorization payload to sign with the developer key. expiresAt: type: string format: date-time title: Expiresat description: UTC timestamp after which this approval is refused. type: object required: - id - payload - expiresAt title: EscrowApprovalView 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 - contact_requires_quote - direct_transfer_unsupported - self_transfer - insufficient_funds - smart_wallet_not_deployed - wallet_owner_unverified - already_funded - funding_in_progress - funding_attempts_exhausted - funding_state_unknown - funding_attempt_expired - contact_changed - user_operation_rejected - user_operation_unavailable - integrator_inactive - client_creation_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 title: PlatformErrorCode securitySchemes: HTTPBearer: type: http scheme: bearer bearerFormat: JWT description: >- Platform access token from `POST /auth/token`, carrying the `platform` audience and the `developer_key_id` of the registration that minted it. It acts as your own account; name a client you created with `X-Hevn-Account: cl_…`. Every request re-checks that the registration is still active and that the caller's source IP is inside its allowlist. A token is valid only against the server that issued it, so sandbox tokens are refused in production and production tokens in the sandbox. ````