Quickstart

Link one client, fund its wallet and settle one holder-approved payout 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.
In the Sign-in window card, add http://localhost:8080 under Allowed sites and save.
Have a second Google account with no HEVN sandbox account. Linking an existing account fails with already_registered.
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 and userId as HEVN_USER_ID. The Python, Node and Go tabs use the reference client.

Serve the two pages

Save both files in an empty folder and serve it on the allowed origin.

index.html

<!doctype html>
<meta charset="utf-8">
<title>HEVN quickstart</title>
<input id="url" placeholder="Paste a session url" size="90">
<button id="open">Open HEVN</button>
<pre id="out"></pre>
<script>
  const out = document.getElementById("out");
  const channel = new BroadcastChannel("hevn-connect");
  channel.onmessage = ({ data }) => { out.textContent = JSON.stringify(data.result, null, 2); };
  document.getElementById("open").onclick = () => {
    window.open(document.getElementById("url").value, "hevn-connect", "popup,width=460,height=720");
  };
</script>

callback.html

<!doctype html>
<meta charset="utf-8">
<title>Signing in…</title>
<script>
  const result = Object.fromEntries(new URLSearchParams(location.search));
  if (result.state) {
    const channel = new BroadcastChannel("hevn-connect");
    channel.postMessage({ state: result.state, result });
    channel.close();
    window.close();
  }
</script>

python3 -m http.server 8080

Open http://localhost:8080. A production page needs the checks in Sign in with HEVN.

Create a link session

Call POST /dapi/v1/connect/sessions with action: "link". Do not send X-Hevn-Account.

curl -s -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"link","redirectUri":"http://localhost:8080/callback.html"}' | jq -r .url

session = hevn.post("/connect/sessions", {
    "action": "link", "redirectUri": "http://localhost:8080/callback.html",
})
print(session["url"])

const session = await hevn.post("/connect/sessions", {
  action: "link", redirectUri: "http://localhost:8080/callback.html",
});
console.log(session.url);

session, err := api.Post("/connect/sessions", hevn.Body{
	"action": "link", "redirectUri": "http://localhost:8080/callback.html",
})
fmt.Println(session.Str("url"))

Response

{ "url": "https://sandbox.gethevn.com/connect?session=eyJ…", … }

Error	Cause
`403 redirect_uri_not_allowed`	`http://localhost:8080` is not an allowed site.
`403 client_creation_not_enabled`	Your account is not an active integrator.

Paste the URL into the page within 10 minutes, click Open HEVN and sign in with the second Google account. The page shows the result.

{ "code": "eyJhbGciOiJFUzI1NiIs…", "state": "pQ8v2Zr0…" }

Exchange the code

Call POST /dapi/v1/clients/link with the code within 5 minutes.

curl -s -X POST "$HEVN_API/clients/link" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"code":"eyJhbGciOiJFUzI1NiIs…"}' | jq '{id, status, baseSmartWallet}'

linked = hevn.post("/clients/link", {"code": code})
client = hevn.acting_as(linked["id"])
ready = poll_until(lambda: client.get("/client"),
                   lambda seen: seen["status"] != "provisioning")

const linked = await hevn.post("/clients/link", { code });
const client = hevn.actingAs(linked.id);
const ready = await pollUntil(() => client.get("/client"),
  (seen) => seen.status !== "provisioning");

linked, err := api.Post("/clients/link", hevn.Body{"code": code})
client := api.ActingAs(linked.Str("id"))
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", "baseSmartWallet": "0x2f1c9d0b8a7e6532d41ac9f0b3e27d5581a4c6f9" }

Export the id as HEVN_CLIENT_ID. While status is provisioning, poll GET /dapi/v1/client with the id in X-Hevn-Account every two seconds.

Fund the wallet

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

curl -X POST "$HEVN_API/sandbox/deposits" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Idempotency-Key: quickstart-deposit-1" \
  -H "Content-Type: application/json" -d '{"amount":"5.00","token":"USDC"}'

credit = client.post("/sandbox/deposits", {"amount": "5.00", "token": "USDC"},
                        idempotency_key="quickstart-deposit-1")

const credit = await client.post("/sandbox/deposits",
  { amount: "5.00", token: "USDC" },
  { idempotencyKey: "quickstart-deposit-1" });

credit, err := client.Post("/sandbox/deposits", hevn.Body{"amount": "5.00", "token": "USDC"},
	hevn.IdempotencyKey("quickstart-deposit-1"))

200 means the tokens are in the wallet. On 202, repeat the request with the same Idempotency-Key.

Read the balance

Call GET /dapi/v1/client/balance. Without X-Hevn-Account the route returns 422.

curl -s "$HEVN_API/client/balance" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" | jq

balance = client.get("/client/balance")

const balance = await client.get("/client/balance");

balance, err := client.Get("/client/balance")

Response

{ "baseSmartWallet": "0x2f1c…", "accounts": [{ "account": "USDC", "balance": "5.000000" }], … }

Book a payout

Read your wallet address from GET /dapi/v1/client/balance with userId from step 1 in X-Hevn-Account. Save it with POST /dapi/v1/contacts, then book 1.00 to it with POST /dapi/v1/payouts.

export HEVN_OWN_WALLET=$(curl -s "$HEVN_API/client/balance" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_USER_ID" | jq -r .baseSmartWallet)

export HEVN_CONTACT_ID=$(curl -s -X POST "$HEVN_API/contacts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Treasury\",\"crypto\":{\"chain\":\"base\",\"token\":\"USDC\",\"address\":\"$HEVN_OWN_WALLET\"}}" | jq -r .id)

curl -s -X POST "$HEVN_API/payouts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Idempotency-Key: quickstart-payout-1" -H "Content-Type: application/json" \
  -d "{\"contactId\":\"$HEVN_CONTACT_ID\",\"amount\":\"1.00\"}"

own_wallet = hevn.acting_as(user_id).get("/client/balance")["baseSmartWallet"]
contact = client.post("/contacts", {
    "name": "Treasury",
    "crypto": {"chain": "base", "token": "USDC", "address": own_wallet},
})
payout = client.post("/payouts", {"contactId": contact["id"], "amount": "1.00"},
                        idempotency_key="quickstart-payout-1")

const { baseSmartWallet: ownWallet } = await hevn.actingAs(userId).get("/client/balance");
const contact = await client.post("/contacts", {
  name: "Treasury",
  crypto: { chain: "base", token: "USDC", address: ownWallet },
});
const payout = await client.post("/payouts", { contactId: contact.id, amount: "1.00" },
  { idempotencyKey: "quickstart-payout-1" });

own, err := api.ActingAs(userID).Get("/client/balance")
contact, err := client.Post("/contacts", hevn.Body{
	"name":   "Treasury",
	"crypto": hevn.Body{"chain": "base", "token": "USDC", "address": own.Str("baseSmartWallet")},
})
payout, err := client.Post("/payouts", hevn.Body{"contactId": contact.Str("id"), "amount": "1.00"},
	hevn.IdempotencyKey("quickstart-payout-1"))

Response

{ "id": "po_6d21…", "status": "awaitingSignature", "authorization": "client", … }

authorization: "client" means the holder approves this payout. Export the id as HEVN_PAYOUT_ID.A new Idempotency-Key books a second payout.

Approve the payout

Call POST /dapi/v1/connect/sessions with action: "sign" and the payout id, then open the URL from the page as in step 4.

curl -s -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d "{\"action\":\"sign\",\"payoutId\":\"$HEVN_PAYOUT_ID\",\"redirectUri\":\"http://localhost:8080/callback.html\"}" \
  | jq -r .url

session = hevn.post("/connect/sessions", {
    "action": "sign", "payoutId": payout["id"],
    "redirectUri": "http://localhost:8080/callback.html",
})

const session = await hevn.post("/connect/sessions", {
  action: "sign", payoutId: payout.id,
  redirectUri: "http://localhost:8080/callback.html",
});

session, err := api.Post("/connect/sessions", hevn.Body{
	"action": "sign", "payoutId": payout.Str("id"),
	"redirectUri": "http://localhost:8080/callback.html",
})

{ "status": "submitted", "payout": "po_6d21…", … }

Read the payout

Do not act on the redirect. Poll GET /dapi/v1/payouts/{payoutId} until the status leaves awaitingSignature and submitted, then read GET /dapi/v1/transactions.

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

done = poll_until(lambda: client.get(f"/payouts/{payout['id']}"),
                  lambda seen: seen["status"] not in ("awaitingSignature", "submitted"))
rows = client.get("/transactions", {"limit": 5})["items"]

const done = await pollUntil(() => client.get(`/payouts/${payout.id}`),
  (seen) => !["awaitingSignature", "submitted"].includes(seen.status));
const { items: rows } = await client.get("/transactions", { limit: 5 });

done, err := hevn.PollUntil(
	func() (hevn.Payload, error) { return client.Get("/payouts/" + payout.Str("id")) },
	func(seen hevn.Payload) bool { s := seen.Str("status"); return s != "awaitingSignature" && s != "submitted" },
	2*time.Minute,
)
page, err := client.Get("/transactions", hevn.Query{"limit": "5"})

Response

{ "status": "settled", "transactionHash": "0x3a77…" }

In the ledger row, from and to are both 1.000000 USDC. To see the 1 USDC in your account, repeat step 7 with $HEVN_USER_ID in X-Hevn-Account.

A transfer to baseSmartWallet and a payout to a wallet contact need a ready client and no verification. Account details and bank payouts need a verified client and an active virtual account. A business verifies through a KYB application, and an individual in a verify session.

HEVN Connect

Before you start

Steps

Next: Sign in with HEVN