Accounts, wallets, and addresses explained

Inside a workspace, key material nests three levels deep. Each level exists for a reason, and knowing which one you are addressing removes most of the guesswork from the endpoint list.

Workspace
└── Account          the secret: a mnemonic (HD) or one imported key (PK)
    └── Wallet       a derivation of that secret; carries tags
        └── Address  one public key, on one VM and one network

Accounts hold the secret

An account is created with POST /v1/accounts and comes in two kinds.

The kind field defaults to HD. Supply secret to import an existing mnemonic (HD) or private key (PK); omit it and an HD account generates its own.

The account slug is generated by the service, not chosen by you. Read it from the create response — it is the identifier every later call uses.

Wallets are derived

A fresh HD account has no wallets. POST /v1/accounts/{slug}/wallets derives them in bulk:

{ "count": 5 }

The response reports the count on both sides of the operation, which makes the call safe to retry and easy to reconcile:

{ "before": 0, "after": 5 }

A PK account instead takes POST /v1/accounts/{slug}/wallets/import with a privateKey, which adds exactly one wallet.

Derivation is bounded: count must be a positive integer up to 500, and the tenant’s limits.maxWallets caps the total. Crossing it returns 409 with quota_wallets_exceeded.

Tags

Wallets carry a free-form list of up to 32 string tags, replaced wholesale with PUT /v1/accounts/{slug}/wallets/{id}/tags. They are yours to use — the service attaches no meaning to them.

Addresses are what you sign with

Each wallet exposes one address per VM, and each address is fixed to a single network:

{ "publicKey": "0xabc…", "vm": "evm", "network": "ethereum", "chainId": 1 }

The signing and transaction endpoints take a public key directly rather than an account/wallet path. You do not walk the tree to sign. Resolution is scoped to your own workspace, so one tenant can never reach another’s key — and an unknown public key returns 404 with account_not_found, the same as a public key that exists but belongs elsewhere.

Related

• Manage accounts and wallets — the task walkthrough
• Accounts endpoints — full request and response shapes
• Scopes and permissions — which scope each operation needs