Clients

A client is your customer’s own HEVN account, linked to your integrator account through Sign in with HEVN. You do not create it with an API call: the account holder creates it in the sign-in window, and POST /dapi/v1/clients/link hands you its id.

POST /dapi/v1/clients/link — 200

{
  "id": "cl_7YQ2Kf3mN8",
  "status": "ready",
  "email": "ops@northwind.example",
  "baseSmartWallet": "0x2f1c9a3b7e5d41c8a06f2d9b4e7c15839af0d6b2",
  "kybStatus": "notStarted",
  "createdAt": "2026-09-17T10:04:11Z",
  "pollUrl": "/dapi/v1/client"
}

email is the address the holder signed in with. A newly created account has nothing else on it yet, so name and phone are usually absent: the company’s identity goes into its verification document, the phone in through PATCH /dapi/v1/client. Responses omit fields with no value, so an absent field and a null field are the same thing — see conventions. Examples use the client from HTTP client. This page straddles the two account scopes: POST /dapi/v1/clients/link and GET /dapi/v1/clients are about your account and refuse X-Hevn-Account with 400 account_scope_conflict, while GET /dapi/v1/client and PATCH /dapi/v1/client act on one client and require it. Sessions has the whole table.

Three statuses

ready means usable. It is the only signal you need before you write the client’s KYB document, open a rail for it or book its payouts. A client the window just created is usually ready by the time you exchange the code; when it is still provisioning, wait for it.

Wait until it is ready

pollUrl carries no id. It is literally /dapi/v1/client, the singular route that reads whichever account X-Hevn-Account names — so a poller sends the cl_… in that header rather than building a path from it.

import random, time


def poll_until(read, done, *, deadline=120.0, first=1.0, cap=8.0):
    """Call read() until done(value) is true. Returns the last value or raises TimeoutError."""
    started, delay = time.monotonic(), first
    while True:
        value = read()
        if done(value):
            return value
        if time.monotonic() - started > deadline:
            raise TimeoutError(f"still {value.get('status')} after {deadline:.0f}s")
        time.sleep(delay + random.uniform(0, delay / 2))
        delay = min(delay * 2, cap)

export async function pollUntil(read, done, { deadline = 120_000, first = 1_000, cap = 8_000 } = {}) {
  const until = Date.now() + deadline;
  let delay = first;
  for (;;) {
    const value = await read();
    if (done(value)) return value;
    if (Date.now() > until) throw new Error(`still ${value.status} after ${deadline}ms`);
    await new Promise((wake) => setTimeout(wake, delay + Math.random() * (delay / 2)));
    delay = Math.min(delay * 2, cap);
  }
}

func PollUntil[T any](read func() (T, error), done func(T) bool, deadline time.Duration) (T, error) {
	until, delay := time.Now().Add(deadline), time.Second
	for {
		value, err := read()
		if err != nil {
			return value, err
		}
		if done(value) {
			return value, nil
		}
		if time.Now().After(until) {
			return value, fmt.Errorf("hevn: still pending after %s", deadline)
		}
		time.Sleep(delay + time.Duration(rand.Int63n(int64(delay/2))))
		if delay < 8*time.Second {
			delay *= 2
		}
	}
}

curl "$HEVN_API/client" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: cl_7YQ2Kf3mN8"

northwind = hevn.acting_as(client["id"])
client = poll_until(
    lambda: northwind.get("/client"),
    lambda c: c["status"] != "provisioning",
)

const northwind = hevn.actingAs(client.id);
const ready = await pollUntil(
  () => northwind.get("/client"),
  (c) => c.status !== "provisioning",
);

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

There is one id to store. cl_7YQ2Kf3mN8 is what you put in X-Hevn-Account: to read this client, to write its KYB document, and to act for it on every money route. Nothing takes it in a path. Keep it in your own records against your own user, server-side — never accept it from a browser, where any page could substitute another customer’s id. baseSmartWallet is the address that holds the client’s balance; keep it for your own reconciliation, but no call takes it as an argument. kybStatus follows the client’s verification from here on — notStarted, then pending, approved, rfi or rejected — and kybApplicationId names the latest submission behind it. Onboarding owns that vocabulary; this row is where you read it without a second call. A failed client answers with a failure object whose code is provisioning_failed, request_rejected or request_canceled. Contact support with the client id.

List your clients

curl "$HEVN_API/clients?status=ready" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN"

mine = hevn.get("/clients", {"status": "ready"})["items"]

const { items: mine } = await hevn.get("/clients", { status: "ready" });

page, err := api.Get("/clients", hevn.Query{"status": "ready"})
mine := page.List("items")

GET /dapi/v1/clients answers { "items": [...], "nextCursor": "..." }, every account connected to you, newest first. It takes status (provisioning, ready, failed), email as an exact, lowercased match, and cursor pagination. It is the place to recover an id you lost: a holder who signs in again through the window also gives you a fresh code for the same client.

Update the phone and the address

PATCH /dapi/v1/client writes two things and nothing else — the phone number the rails check, and the postal address. It is a client-scoped route, so the id travels in X-Hevn-Account:

curl -X PATCH "$HEVN_API/client" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: cl_7YQ2Kf3mN8" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+13125550142"}'

patched = hevn.acting_as(client_id).patch("/client", {"phone": "+13125550142"})

const patched = await hevn.actingAs(clientId).patch("/client", { phone: "+13125550142" });

patched, err := api.ActingAs(clientID).Patch("/client", hevn.Body{"phone": "+13125550142"})

phone is E.164, for example +13125550142. Every rail a company opens checks for a phone number on the account, so set it before you open one. address takes streetAddress, addressLine2, city, state and zip. Only the keys you send are written. Everything else a company has to tell HEVN is verification data and belongs in its KYB document. The address country is frozen at registration; changing a locked field answers 409 profile_locked with details.fields.

What you can do with a client

Linking gives your integrator account a seat on the client’s account. With it you read and write everything a finance team would set up — the verification document, rails, contacts, payins, the ledger — and you book payouts. You never sign them: the account holder’s own key is the only one that can spend from their wallet, and they approve each payout in the sign-in window. Your developer key has no power over the client’s money at all. That is the whole point of the model — see accounts and control.

Next: Onboard a client

Fill the KYB document, upload its papers, submit, and answer an RFI.

Start here

Core concepts

Onboard a client

Move money

Escrow

Ship it

Reference

Three statuses

Wait until it is ready

List your clients

Update the phone and the address

What you can do with a client

Next: Onboard a client

​Three statuses

​Wait until it is ready

​List your clients

​Update the phone and the address

​What you can do with a client

Next: Onboard a client

Three statuses

Wait until it is ready

List your clients

Update the phone and the address

What you can do with a client