REST API overview

The published contract for every operation of the HEVN Platform API, grouped the way the whitelabel guide is.

This tab is generated from the HEVN Platform API’s OpenAPI document: every operation, each with a schema, request examples and an interactive playground. The API serves that document itself, at https://sandbox-api.hevn.finance/dapi/v1/openapi.json, with Swagger UI at https://sandbox-api.hevn.finance/dapi/v1/docs — so the running deployment is always the authority for a field.

It is the machine-readable half of the Whitelabel guide. The guide explains the model — your integrator account, the client accounts you create, the developer key that signs their money out. This reference is the exact contract for every call, and its groups follow the guide’s order: log in, create a client, submit its verification, open a rail, move money, operate escrow.

Whitelabel overview

What you can build, and the object graph behind it.

Quickstart

Nine steps in the sandbox, from an empty account to money that moved on chain.

Servers

Environment	Server	Notes
Production	https://api.hevn.finance/dapi/v1	Real money, Base.
Sandbox	https://sandbox-api.hevn.finance/dapi/v1	Test funds, Base Sepolia, one emulated partner.

The document the API serves declares one relative server, /dapi/v1, so the host decides which of the two rows above you are talking to; the copy published in this tab names both hosts so the playground can pick one. Every path in this reference hangs off that base: a full URL is https://api.hevn.finance/dapi/v1/banks, and so is every Location header and every pollUrl the API answers with — both are absolute paths from the host root that already begin /dapi/v1. The two deployments have separate accounts, and a token issued by one is refused by the other, so pick the host before you send a request.

The operations tagged sandbox exist on the sandbox host only; production answers 404 for them. Everything else exists on both.

The bearer model

Every operation but the three under auth takes one header:

Authorization: Bearer <accessToken>

The access token is a short-lived JWT your backend mints for itself by signing a challenge with your registered developer key. It is the only credential this API accepts. Its audience is platform and it carries a developer_key_id claim naming the developer key that established the session; a request under /dapi/v1 carrying anything else — no bearer, an ordinary API token, or the platform-refresh token — is refused before it reaches a route, with 401 unauthenticated or 403 forbidden and details.reason: "developerSessionRequired". Ordinary /api/v1 routes refuse a platform token just as firmly, in the other direction.

The schema shows an optional x-api-key parameter on every operation. That is an artefact of a shared dependency, not a credential: an API key belongs to the CLI and can never authenticate here, because the boundary refuses the request before the key is read.

HEVN re-reads the developer key on every request: it must still exist, the request must arrive from an address inside the immutable allowlist set when the key was created, and the operation must be one the key’s scopes open. A deleted key, a new egress IP or a missing scope is a 403 on every operation, whatever the token says — see Developer key.

To act for one of your clients, send that client’s id in a second header instead of minting a second token:

X-Hevn-Account: cl_7YQ2Kf3mN8

No operation names a client in its path; the header is the only selector, and operations fall into three groups. Most accept it and act on your own account when you omit it. The singular /client, /client/balance, /client/kyb and /client/kyb/complete require it — the spec marks it required: true, and omitting it is a 422 validation_failed on a missing header, not a read of your own account. Operations that are about your own account by definition — POST /clients, GET /clients and all of escrow — refuse it with 400 account_scope_conflict and details.reason: "selfScopedRoute". The three under auth ignore it: a login has no account to act for yet. The full table is in Sessions.

One error envelope

Every refusal, on every route, has the same body:

{
  "error": {
    "code": "insufficient_funds",
    "message": "The account's USDC balance does not cover this transfer.",
    "details": { "available": "3000000", "required": "5000000" }
  }
}

code is a stable lowercase slug — branch on it, never on message. The spec publishes the whole slug enum as PlatformErrorCode, not a per-operation list, so the registry with what to do about each is in Errors. Every response carries an X-Request-ID; quote it in a support request.

Conventions this reference assumes

Bodies, query parameters and response fields are camelCase; unknown keys are refused rather than ignored; null fields are omitted, so absent and null are the same thing. Money is always a decimal string in the asset’s major unit ("500.00"), never a JSON number. Ids are opaque and prefixed by what they name. Lists page with a cursor. Idempotency-Key is accepted on every write and required on none. All seven rules, in one page: Conventions.

Money movement is signed

Reading data and writing metadata need only a token. Moving money needs a signature from your developer key, and every such operation is a pair: an opening call that prices and builds the operation and hands you an approval.payload, then a confirm that carries your signature over the decoded bytes of that payload.

What moves	Prepare	Confirm
Fiat out over a bank rail, or USDC out on Base	POST /payouts	POST /payouts/{payoutId}/confirm
An escrow deal or action	POST /escrow, POST /escrow/{escrowId}/actions	POST /escrow/{escrowId}/actions/{idempotencyKey}/confirm

One mechanism, described once in Signing.

Authentication

The two login calls, the two tokens, and the header that picks the account.

HTTP client

A working client in Python, Node and Go: login, retries, signing, polling.