Add an account

curl --request POST \
  --url https://api.example.com/client/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Hevn-Account: <x-hevn-account>' \
  --data '
{
  "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  "kind": "external"
}
'

import requests

url = "https://api.example.com/client/accounts"

payload = {
    "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "kind": "external"
}
headers = {
    "X-Hevn-Account": "<x-hevn-account>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Hevn-Account': '<x-hevn-account>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({address: '0x8ba1f109551bD432803012645Ac136ddd64DBA72', kind: 'external'})
};

fetch('https://api.example.com/client/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "accountId": "acc_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "kind": "external",
  "asset": "USDC",
  "chain": "base",
  "address": "<string>",
  "balance": "500.00",
  "createdAt": "2023-11-07T05:31:56Z",
  "label": "<string>",
  "syncedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

Accounts

Add an account

Without kind, or with kind: external: register an address for the client on chain (base, arb, eth, op, pol or sol). A receiving account opened on it delivers USDC on that network, an on-chain pay-in can be delivered to it, and a Base address can fund payouts it sends itself. Answers 201 the first time and 200 with Idempotency-Replayed: true when the same address was already added with the same label; another label is account_address_taken.

With kind: sub: open a sub account, a further wallet of your own account on Base that holds one token, asset: USDC (the default) or RD. The token is chosen once; receiving accounts, payouts and moves of the account run in it, and money moves only between accounts of the same token. Its address takes deposits at once; another token sent to it is not in balance and can only be moved out to the account’s wallet with a swap. Name it as sourceAccount or destinationAccount on payouts, pay-ins and swaps, and as accountId on a receiving account; a payout or swap that leaves it is signed with your developer key, exactly like one that leaves the account’s wallet. A create whose label and asset a sub account already carries answers 200 with that account; the same label with another asset, or a create without label, opens a new one. A sub account is opened on your own account only: a request that acts for a client returns 403 account_not_controlled. An account whose wallet is not protected by co-signing returns 409 safe_mode_required. A sub account cannot be archived.

POST

client

accounts

Add an account

curl --request POST \
  --url https://api.example.com/client/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Hevn-Account: <x-hevn-account>' \
  --data '
{
  "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  "kind": "external"
}
'

import requests

url = "https://api.example.com/client/accounts"

payload = {
    "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "kind": "external"
}
headers = {
    "X-Hevn-Account": "<x-hevn-account>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Hevn-Account': '<x-hevn-account>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({address: '0x8ba1f109551bD432803012645Ac136ddd64DBA72', kind: 'external'})
};

fetch('https://api.example.com/client/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "accountId": "acc_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "kind": "external",
  "asset": "USDC",
  "chain": "base",
  "address": "<string>",
  "balance": "500.00",
  "createdAt": "2023-11-07T05:31:56Z",
  "label": "<string>",
  "syncedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Hevn-Account

string

required

The selected client account, as a cl_… id.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

Idempotency-Key

string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

Body

application/json

ClientExternalAccountRequest
ClientSubAccountRequest

chain

enum<string>

required

Network the address receives USDC on: base, arb, eth, op, pol or sol.

Available options:

base,

arb,

eth,

op,

pol,

sol

address

string

required

Address on chain: a 0x address on EVM networks, a base58 address on Solana.

Required string length: 1 - 64

Example:

"0x8ba1f109551bD432803012645Ac136ddd64DBA72"

kind

string

default:external

external, the default: an address the client holds and signs for itself.

Allowed value: "external"

label

string | null

Name shown for this address.

Maximum string length: 64

Response

Successful Response

accountId

string

required

Stable public identifier of this account, as an acc_ id.

Pattern: ^(?:acc_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"acc_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

kind

enum<string>

required

external: an address the client holds and signs for itself. sub: a further wallet of the client that HEVN opened, spent with your developer key.

Available options:

external,

sub

asset

enum<string>

required

The token the account holds: USDC, or RD for a sub account opened with asset: RD.

Available options:

USDC,

RD

chain

enum<string>

required

Network the address holds asset on. Always base for a sub account.

Available options:

base,

arb,

eth,

op,

pol,

sol

address

string

required

Address on chain.

balance

string

required

asset held at the address on chain, read from the network when older than a minute and kept as last read when the network does not answer.

Example:

"500.00"

createdAt

string<date-time>

required

UTC timestamp when the account was added.

label

string | null

Name shown for this account.

syncedAt

string<date-time> | null

UTC timestamp of the last successful balance read.

Overview

Authentication

Clients

Accounts

Verification

Virtual accounts

Money in

Money out

Swaps

Contacts

Transactions

Catalog

Escrow

Sandbox

Add an account

Authorizations

Headers

Body

Response