> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockops.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets & accounts

> Create an MPC wallet, attach assets to get deposit addresses, receive funds, and read balances.

## Create a wallet

Wallet creation is asynchronous. The API records the request and returns at once; the signing cluster then runs distributed key generation, and the wallet becomes `active` when its public key has been stored. Locally this takes seconds; allow up to a minute.

```bash theme={null}
curl -X POST https://<api-host>/api/v1/wallets \
  -H "ACCESS-API-KEY: $KEY" -H "ACCESS-TIMESTAMP: $TS" -H "ACCESS-SIGN: $SIG" \
  -H "X-Idempotency-Key: 5f9a…" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": "<workspace_id>", "name": "Treasury", "wallet_type": "mpc"}'
```

The response is `202 Accepted` with a wallet operation: the new `wallet_id` and `status: "pending"`. Poll the operation until it completes:

```bash theme={null}
GET /api/v1/wallets/creation-status/{wallet_id}
```

| Status      | Meaning                                                                                                               |
| :---------- | :-------------------------------------------------------------------------------------------------------------------- |
| `pending`   | Recorded; key generation not yet published.                                                                           |
| `submitted` | Key generation is running on the cluster.                                                                             |
| `success`   | The wallet is `active` and can hold assets.                                                                           |
| `failed`    | Key generation failed or timed out; the reason is in `status_reason`. Create a new wallet with a new idempotency key. |

Or subscribe to the `wallet.creation_requested` and `wallet.created` events; see [Webhooks & events](/wallets/webhooks-and-events).

Repeating the `POST` with the same `X-Idempotency-Key` returns the same operation; it never starts a second key generation.

**In the console:** Wallet → **Create Wallet** → choose **MPC Wallet**, name it, confirm. The console polls creation status and opens the wallet when it is ready.

## Read wallets

```bash theme={null}
GET /api/v1/workspaces/{workspace_id}/wallets      # list
GET /api/v1/wallets/{wallet_id}                    # detail
```

## Attach an asset and get a deposit address

A wallet holds funds per **asset** (a network plus, for tokens, a contract). Attaching an asset derives the wallet's deposit address on that network from its public key. Asset IDs come from the catalog:

```bash theme={null}
GET /api/v1/networks          # supported networks
GET /api/v1/assets            # catalog assets, with network, decimals, native/token flag
PUT /api/v1/wallets/{wallet_id}/asset/{asset_id}   # attach; returns the wallet asset and its address
```

Attaching the same asset twice is idempotent. The derivation path is fixed on the server; the API does not accept client-supplied paths. Read addresses and attached assets with:

```bash theme={null}
GET /api/v1/wallets/{wallet_id}/assets
GET /api/v1/wallets/{wallet_id}/deposit-address?asset_id={asset_id}
```

**In the console:** open the wallet → **Receive** → choose the asset. The console attaches it if needed and shows the address and a QR code.

## Receive funds

Anything sent to a deposit address is picked up by the chain scanner. A deposit is recorded as an inbound transaction when it is observed and credited to the balance once it reaches the configured confirmation depth for that asset. If the chain reorganises below that depth, the deposit is marked failed and the affected blocks are rescanned; balances are only ever credited from canonical blocks.

Events: `deposit.detected`, `deposit.failed`, `balance.updated`.

## Read balances

```bash theme={null}
GET /api/v1/wallets/{wallet_id}/balance/{asset_id}   # one asset
GET /api/v1/wallets/{wallet_id}/overview             # all attached assets
```

Balances are chain-observed snapshots written by the scanner, not running totals kept by the API. Each balance shows what is available and what is held by in-flight withdrawals. If the scanner falls behind, the last known balance is returned; a stale scanner never reports zero.

## Supported networks

Wallets can hold native assets and tokens on the EVM networks listed for MPC Wallet Infrastructure on [Supported networks & assets](/overview/supported-networks). Ethereum Sepolia is available in the sandbox.