---
title: "Accounts, wallets, and addresses explained"
description: "How key material is organised — HD versus PK accounts, derived wallets, and the addresses you sign with."
---

> Documentation Index
> Fetch the complete documentation index at: https://tee.hypetrade.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

| Kind | Secret | Derivation |
|---|---|---|
| `HD` | A BIP-39 mnemonic, generated when you do not supply one | Many wallets from one mnemonic |
| `PK` | A single imported private key | No derivation |

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.

> **Secrets never come back in a response**
>
> A generated mnemonic is not returned. `POST /v1/accounts` answers with
> `generatedSecret: true` to tell you one was created, and nothing more. The only
> way key material leaves the service is the sealed
> [export path](/guides/export-key-material/), encrypted to a public key your
> operator registered by hand.

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:

```json
{ "count": 5 }
```

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

```json
{ "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:

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

> **The account chooses the chain, once**
>
> Which network an address carries comes from its account's `defaultNetwork`,
> set when the account is created and **not changeable afterwards** — no route
> updates it.
>
> Nothing else selects a chain either: the transaction routes take a public key
> and derive the network from it, so there is no `network` field on a build or a
> send. Sending on Base rather than Ethereum therefore means using an address
> from an account created with `defaultNetwork: "base"`.
>
> Plan for that at creation time. If you expect to work across chains, create one
> account per chain up front — switching later means creating the account you
> should have had.

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.

> **VM mismatches are a distinct error**
>
> Asking an address to do something its VM cannot — typed-data signing on a
> non-EVM address, exporting an `svm` key from a wallet with no Solana address —
> returns `422` with `unsupported_for_kind`, not a validation error.

## Related

- [Manage accounts and wallets](/guides/manage-accounts-and-wallets/) — the task walkthrough
- [Accounts endpoints](/api/accounts/) — full request and response shapes
- [Scopes and permissions](/concepts/scopes/) — which scope each operation needs

Source: https://tee.hypetrade.xyz/concepts/accounts-wallets-addresses/index.mdx