Quickstart

Create one client, register a wallet address for it and receive one emulated bank payin on that address in the sandbox. Start by logging in with POST /dapi/v1/auth/challenge and POST /dapi/v1/auth/token.

Before you start

Sign up at https://sandbox.gethevn.com.
Open Settings → Partner program → Developer and create a developer key. Set its IP allowlist to your machine’s egress address.
Save the private key to $HEVN_KEY_PEM with mode 0600.
Ask HEVN to enable client creation for your sandbox account.
Create a wallet on Base Sepolia whose key you hold. It stands in for your customer’s wallet. Export its address as HEVN_WALLET.
Set the environment and install the dependencies.

Environment	API base URL	App	Chain
Sandbox	`https://sandbox-api.hevn.finance/dapi/v1`	`https://sandbox.gethevn.com`	Base Sepolia
Production	`https://api.hevn.finance/dapi/v1`	`https://app.gethevn.com`	Base

Developer keys, clients and tokens are per environment. The examples read these variables:

export HEVN_API="https://sandbox-api.hevn.finance/dapi/v1"
export HEVN_EMAIL="[email protected]"
export HEVN_KEY_PEM="$HOME/.hevn/developer-key.pem"  # mode 0600, keep it out of your repo
export HEVN_CLIENT_ID="cl_7YQ2Kf3mN8"                # the client a call acts for

Derived variable	Value
`HEVN_ACCESS_TOKEN`	The `accessToken` returned by login.
`HEVN_USER_ID`	Your `cl_…` id, the `userId` returned by login.
`HEVN_PUBLIC_KEY`	The base64 public key of the PEM, sent as `publicKey` to `POST /dapi/v1/payouts`.

export HEVN_PUBLIC_KEY=$(openssl ec -in "$HEVN_KEY_PEM" -pubout -outform DER 2>/dev/null \
  | base64 | tr -d '\n')

python -m venv .venv && source .venv/bin/activate
pip install cryptography httpx

# Node 20 or newer. Signing and HTTP use node:crypto and global fetch.
node --version
npm init --yes

go mod init example.com/hevn
# Signing and HTTP use the standard library only: crypto/ecdsa, encoding/pem, net/http.

The sandbox runs on Base Sepolia with testnet tokens. A payout, escrow or payin is capped at 1, and a faucet credit at 5 to a wallet holding less than 1. The sandbox money routes take 60 calls per account per hour. See Sandbox limits.

Steps

Run the login code in Sessions. Export accessToken as HEVN_ACCESS_TOKEN. The Python, Node and Go tabs use the reference client.

Create the client

Call POST /dapi/v1/clients with the company’s legal name and email. Do not send X-Hevn-Account.

curl -s -X POST "$HEVN_API/clients" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Idempotency-Key: quickstart-client-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Trading LLC","email":"[email protected]","phone":"+13125550142"}'

created = hevn.post("/clients", {
    "name": "Example Trading LLC",
    "email": "[email protected]",
    "phone": "+13125550142",
}, idempotency_key="quickstart-client-1")
client = hevn.acting_as(created["id"])

const created = await hevn.post("/clients", {
  name: "Example Trading LLC",
  email: "[email protected]",
  phone: "+13125550142",
}, { idempotencyKey: "quickstart-client-1" });
const client = hevn.actingAs(created.id);

created, err := api.Post("/clients", hevn.Body{
	"name":  "Example Trading LLC",
	"email": "[email protected]",
	"phone": "+13125550142",
}, hevn.IdempotencyKey("quickstart-client-1"))
client := api.ActingAs(created.Str("id"))

Response 202

{ "id": "cl_7YQ2Kf3mN8", "status": "provisioning", "name": "Example Trading LLC",
  "kybStatus": "notStarted", "pollUrl": "/dapi/v1/client", … }

Export the id as HEVN_CLIENT_ID. A retry with the same Idempotency-Key returns the same client. Fields: Create a client.

Error	Cause
`403 client_creation_not_enabled`	HEVN has not enabled client creation for your account.
`400 account_scope_conflict`	The request has `X-Hevn-Account`.
`409 idempotency_key_reused`	The key was used with another body.

Call POST /dapi/v1/client/accounts with the client id in X-Hevn-Account.

export HEVN_ACCOUNT_ID=$(curl -s -X POST "$HEVN_API/client/accounts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"chain\":\"base\",\"address\":\"$HEVN_WALLET\",\"label\":\"Treasury wallet\"}" | jq -r .accountId)

account = client.post("/client/accounts", {
    "chain": "base", "address": os.environ["HEVN_WALLET"], "label": "Treasury wallet",
})

const account = await client.post("/client/accounts", {
  chain: "base", address: process.env.HEVN_WALLET, label: "Treasury wallet",
});

account, err := client.Post("/client/accounts", hevn.Body{
	"chain": "base", "address": os.Getenv("HEVN_WALLET"), "label": "Treasury wallet",
})

Response 201

{ "accountId": "acc_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41", "kind": "external", "asset": "USDC",
  "chain": "base", "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72", "balance": "0.0", … }

While HEVN reviews the client request, the call returns 404 account_not_found. Repeat it with the same body. Rules and refusals are in External accounts.

Wait for the client

Poll GET /dapi/v1/client every two seconds until status is ready.

curl -s "$HEVN_API/client" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" | jq '{id, status, kybStatus}'

ready = poll_until(lambda: client.get("/client"),
                   lambda seen: seen["status"] != "provisioning")

const ready = await pollUntil(() => client.get("/client"),
  (seen) => seen.status !== "provisioning");

ready, err := hevn.PollUntil(
	func() (hevn.Payload, error) { return client.Get("/client") },
	func(seen hevn.Payload) bool { return seen.Str("status") != "provisioning" },
	2*time.Minute,
)

Response

{ "id": "cl_7YQ2Kf3mN8", "status": "ready", "kybStatus": "notStarted", … }

The statuses are in Statuses.

Verify the client

Write the KYB document with PUT /dapi/v1/client/kyb as in Write the document. When it returns ready: true, call POST /dapi/v1/client/kyb/complete, then approve the application with POST /dapi/v1/sandbox/kyb/status.

curl -s -X POST "$HEVN_API/client/kyb/complete" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID"

curl -s -X POST "$HEVN_API/sandbox/kyb/status" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" -d '{"status":"approved"}'

application = client.post("/client/kyb/complete")
kyb = client.post("/sandbox/kyb/status", {"status": "approved"})

const application = await client.post("/client/kyb/complete");
const kyb = await client.post("/sandbox/kyb/status", { status: "approved" });

application, err := client.Post("/client/kyb/complete", nil)
kyb, err := client.Post("/sandbox/kyb/status", hevn.Body{"status": "approved"})

In production HEVN reviews the application (Track the application).

Request a virtual account

Call POST /dapi/v1/banks with a product and the accountId, then poll GET /dapi/v1/banks/{product} with the same accountId until status is active.

curl -s -X POST "$HEVN_API/banks" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"product\":\"us\",\"accountId\":\"$HEVN_ACCOUNT_ID\"}"

export HEVN_BANK_ID=$(curl -s "$HEVN_API/banks/us?accountId=$HEVN_ACCOUNT_ID" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" | jq -r .id)

client.post("/banks", {"product": "us", "accountId": account["accountId"]})
bank = poll_until(lambda: client.get("/banks/us", {"accountId": account["accountId"]}),
                  lambda seen: seen.get("status") != "preparing")

await client.post("/banks", { product: "us", accountId: account.accountId });
const bank = await pollUntil(() => client.get("/banks/us", { accountId: account.accountId }),
  (seen) => seen.status !== "preparing");

_, err = client.Post("/banks", hevn.Body{"product": "us", "accountId": account.Str("accountId")})
bank, err := hevn.PollUntil(
	func() (hevn.Payload, error) {
		return client.Get("/banks/us", hevn.Query{"accountId": account.Str("accountId")})
	},
	func(seen hevn.Payload) bool { return seen.Str("status") != "preparing" },
	2*time.Minute,
)

Response

{ "product": "us", "status": "active", "id": "bnk_5Hq2…", "accountId": "acc_9f2c…",
  "requisites": { … }, "blockers": [], … }

While status is preparing, read blockers[] (What still blocks it). A product that cannot deliver to the address returns 409 account_destination_unsupported.

Emulate a bank payin

Call POST /dapi/v1/sandbox/deposits with the bankId. Do not send accountId or token.

curl -s -X POST "$HEVN_API/sandbox/deposits" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Idempotency-Key: quickstart-wire-1" -H "Content-Type: application/json" \
  -d "{\"amount\":\"1.00\",\"bankId\":\"$HEVN_BANK_ID\",\"remitter\":\"Payer Inc\"}"

credit = client.post("/sandbox/deposits",
                     {"amount": "1.00", "bankId": bank["id"], "remitter": "Payer Inc"},
                     idempotency_key="quickstart-wire-1")

const credit = await client.post("/sandbox/deposits",
  { amount: "1.00", bankId: bank.id, remitter: "Payer Inc" },
  { idempotencyKey: "quickstart-wire-1" });

credit, err := client.Post("/sandbox/deposits",
	hevn.Body{"amount": "1.00", "bankId": bank.Str("id"), "remitter": "Payer Inc"},
	hevn.IdempotencyKey("quickstart-wire-1"))

Response: 200

{ "depositId": "sbx_…", "status": "settled", "token": "USDC", "amount": "1.00", "currency": "USD",
  "accountId": "acc_9f2c…", "txHash": "0x08fa…", "transactionId": "txn_9e4…", … }

On 202, repeat the request with the same Idempotency-Key. The testnet USDC is sent to $HEVN_WALLET.

Read the ledger and balance

Call GET /dapi/v1/transactions with accountId, then GET /dapi/v1/client/accounts/{accountId}.

curl -s "$HEVN_API/transactions?accountId=$HEVN_ACCOUNT_ID&limit=5" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  | jq '.items[] | {id, status, isIncome, accountId, to}'

curl -s "$HEVN_API/client/accounts/$HEVN_ACCOUNT_ID" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  | jq '{balance, syncedAt}'

rows = client.get("/transactions", {"accountId": account["accountId"], "limit": 5})["items"]
seen = client.get(f"/client/accounts/{account['accountId']}")
print(seen["balance"], seen.get("syncedAt"))

const { items: rows } = await client.get("/transactions", { accountId: account.accountId, limit: 5 });
const seen = await client.get(`/client/accounts/${account.accountId}`);
console.log(seen.balance, seen.syncedAt);

page, err := client.Get("/transactions", hevn.Query{"accountId": account.Str("accountId"), "limit": "5"})
seen, err := client.Get("/client/accounts/" + account.Str("accountId"))
fmt.Println(seen.Str("balance"), seen.Str("syncedAt"))

balance is refreshed when the stored value is older than a minute. GET /dapi/v1/client/balance has no row for the account.

To pay out from the address, fund it with testnet USDC and follow Payouts. The sandbox faucet route does not credit an external account.

External wallets

Before you start

Steps

Next: External accounts