Clients

A client is a real HEVN account whose wallet your key controls. One call creates it; one id identifies it forever.

curl -X POST "$HEVN_API/clients" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Northwind Trading Ltd","email":"ops@northwind.example","phone":"+13125550142"}'

client = hevn.post("/clients", {
    "name": "Northwind Trading Ltd",
    "email": "ops@northwind.example",
    "phone": "+13125550142",
})

const client = await hevn.post("/clients", {
  name: "Northwind Trading Ltd",
  email: "ops@northwind.example",
  phone: "+13125550142",
});

client, err := api.Post("/clients", hevn.Body{
	"name":  "Northwind Trading Ltd",
	"email": "ops@northwind.example",
	"phone": "+13125550142",
})

201 Created, Location: /dapi/v1/client:

{
  "id": "cl_7YQ2Kf3mN8",
  "status": "provisioning",
  "name": "Northwind Trading Ltd",
  "email": "ops@northwind.example",
  "phone": "+13125550142",
  "kybStatus": "notStarted",
  "createdAt": "2026-09-17T10:04:11Z",
  "pollUrl": "/dapi/v1/client"
}

baseSmartWallet is absent because it does not exist yet. Responses omit fields with no value, so an absent field and a null field are the same thing — see conventions. 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 new cl_… in that header rather than building a path from it. Examples use the client from HTTP client. This page straddles the two account scopes: POST /dapi/v1/clients and GET /dapi/v1/clients are the collection you own 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.

The three fields

string

required

The company’s legal name. It becomes the client’s account name and the legal name of its KYB subject, so you write it once and never again. Uniqueness is global across HEVN — a generic name answers 409 name_in_use.

string

required

The client’s identity, lowercased server-side. HEVN sends no mail to this address: the account’s own seat is an administrator seat, and administrators are not mail recipients. Treat it as an identifier and as your recovery key for a lost response.

string

E.164, for example +13125550142. Optional here and required later: every rail a company opens checks for a phone number on the account. Passing it at creation is the difference between opening a rail in one call and opening it in two.

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 move its money.

Wait until it is ready

Read the client until its status changes. pollUrl on the create response is the path, and the id you were given goes in X-Hevn-Account.

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)

A ready client carries the address that holds its money:

{
  "id": "cl_7YQ2Kf3mN8",
  "status": "ready",
  "name": "Northwind Trading Ltd",
  "email": "ops@northwind.example",
  "phone": "+13125550142",
  "baseSmartWallet": "0x2f1c9a3b7e5d41c8a06f2d9b4e7c15839af0d6b2",
  "kybStatus": "notStarted",
  "createdAt": "2026-09-17T10:04:11Z"
}

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. baseSmartWallet is the address that holds its balance; keep it for your own reconciliation, but no call takes it as an argument. Idempotency-Key is accepted on the create and is not needed: an identical retry replays rather than creating a second company, and an open request for the same email is deduplicated whether you sent a key or not. 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.

If provisioning fails

A failed client answers with a failure object and stays in your list:

{
  "id": "cl_7YQ2Kf3mN8",
  "status": "failed",
  "failure": {
    "code": "provisioning_failed",
    "message": "Provisioning this client did not complete. Contact support with the client id.",
    "retriable": false
  }
}

The codes are provisioning_failed, request_rejected and request_canceled. The id and the email stay taken in all three cases, so re-sending the same body answers 409 email_in_use rather than starting over. Contact support with the client id.

Recover a lost response

The email is the recovery key. If a create call timed out and you never saw the id, ask for it back instead of creating a second company:

curl "$HEVN_API/clients?email=ops@northwind.example" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN"

found = hevn.get("/clients", {"email": "ops@northwind.example"})["items"]

const { items: found } = await hevn.get("/clients", { email: "ops@northwind.example" });

page, err := api.Get("/clients", hevn.Query{"email": "ops@northwind.example"})
found := page.List("items")

GET /dapi/v1/clients answers { "items": [...], "nextCursor": "..." }, newest first, and includes clients that are still provisioning. It also takes status (provisioning, ready, failed) and cursor pagination. Re-sending an identical create body while the first request is still open replays it and answers 200 with Idempotency-Replayed: true and the same id; a different name or phone for the same open email answers 409 client_request_conflict.

Creating clients at scale

Two things bite when you onboard in bulk rather than one at a time. The first is name. Uniqueness is global across HEVN, not per integrator, so a generic trading name will eventually answer 409 name_in_use against a company that is not yours. Send the registered legal name, including its suffix — Northwind Trading Ltd, not Northwind — and treat the 409 as a signal to ask your customer for the exact name on their certificate, not as a reason to append a number. The second is concurrency. Client creation is a queued operation; ready arrives in roughly 30 seconds under normal load and there is no ordering guarantee between two creates. Poll each client independently rather than waiting for a batch, and do not hold a request open waiting for the wallet.

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"})

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 your key can do with a client

Your developer key is the only key on your side that can authorize a spend from this client’s wallet — HEVN co-signs the operation it built, and neither signature alone is a quorum. The client has no signer of its own and no login. That is the whole point of the whitelabel model, and it is the one thing to be deliberate about before you create your first client in production — 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

The three fields

Three statuses

Wait until it is ready

If provisioning fails

Recover a lost response

Creating clients at scale

Update the phone and the address

What your key can do with a client

Next: Onboard a client

​The three fields

​Three statuses

​Wait until it is ready

​If provisioning fails

​Recover a lost response

​Creating clients at scale

​Update the phone and the address

​What your key can do with a client

Next: Onboard a client

The three fields

Three statuses

Wait until it is ready

If provisioning fails

Recover a lost response

Creating clients at scale

Update the phone and the address

What your key can do with a client