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

# Create a wallet

> Start an organisation wallet, or a member's own personal wallet, with the owners who approve it, follow its creation and withdraw it.

A member's own API key can start an organisation wallet (with `treasury_write`) or the member's own personal wallet (with `orders_write`, where Advanced is enabled). Each owner chooses their own sign-in methods and approves it on their own signing page, so no wallet exists at the provider until they have.

## At a glance

Paths are under `/api/v1/workspaces/{workspaceId}`.

| Call (scope) | Does |
| - | - |
| `POST …/wallets` (`orders_write` or `treasury_write`) | Starts a wallet |
| `GET …/wallets/{walletId}` (`treasury_read`) | Follows one creation |
| `GET …/wallets?status=pending` (`treasury_read`) | Lists pending creations |
| `POST …/wallets/{walletId}/cancel` (as its create) | Withdraws a creation |

The key's member also needs View wallets for a personal wallet, or Manage wallets for an organisation wallet.

**1. Start it**

`POST /api/v1/workspaces/{workspaceId}/wallets` with `scope` (`organisation`, or `personal` for the key's own member), a `connectionId` (a workspace wallet connection, or `platform-turnkey`), `family`, `networks`, `displayName` and an `ownerGroup`: the people who approve, each with an empty `factors` list and no `walletId`, and the `threshold`. A personal wallet's group is the key's member alone, threshold 1. Send an `Idempotency-Key`. The answer is `202` with the pending wallet and `signingRequest.approvalUrl`.

```json Request body theme={null}
{
  "scope": "organisation",
  "connectionId": "platform-turnkey",
  "family": "evm",
  "networks": ["eip155:84532"],
  "displayName": "Treasury",
  "ownerGroup": {
    "members": [
      { "person": "<workspace user id>", "factors": [], "needed": 1 },
      { "person": "<workspace user id>", "factors": [], "needed": 1 }
    ],
    "threshold": 2
  }
}
```

**2. Send the owners to approve**

Each owner, the key's member included, opens `approvalUrl`, signs in, chooses their sign-in methods and proves them. For an organisation wallet the key's member first confirms it was them with an authenticator app or security key. With `returnUrl`, on one of the workspace's registered wallet callback origins, the page sends them back with `signingRequestId` and `outcome`.

**3. Follow it**

`GET …/wallets/{walletId}` until `status` is `active`, or `failed`, `expired`, `cancelled` or `declined`; after any of the last four, start again. `missing` names who has not approved yet. `GET …/wallets?status=pending` lists the pending ones.

> [accordion] What a key may not do
>
> A key never names how a person approves: an owner sent with factors or a `walletId` is `403 API_KEY_WALLET_FACTORS_REFUSED`, and nothing is recorded. Each person picks their own sign-in methods or wallet on the approval page. A key needs the scope its body needs: `orders_write` for a personal wallet, `treasury_write` for an organisation wallet (`403 INSUFFICIENT_SCOPE` otherwise, with `details.requiredScope`). A key holding neither is refused before its body is read, and that refusal's `details.requiredScope` names `orders_write`. A personal wallet where Advanced is not enabled is `403 ADVANCED_MODE_DISABLED`, and a service account's key is `403 API_KEY_WALLET_CREATOR_NOT_A_PERSON`. A key sends no `stepUpProof`, `tradeFromThisWallet` or `initialAccess` (`403 API_KEY_WALLET_GRANT_REFUSED`): set access and grants in the app. An API key never approves.

> [accordion] Withdraw a creation
>
> `POST …/wallets/{walletId}/cancel` with an `Idempotency-Key`, and the scope the creation needed. A `pending` creation is withdrawn at once and reads `cancelled`. An `uncertain` one is checked at the provider first and refused by name when the wallet may exist there. Any other status is `409 WALLET_CREATION_NOT_CANCELLABLE`.

> [accordion] Status values
>
> `pending`, `creating`, `uncertain`, `created`, `active`, `readbackMismatch`, `failed`, `expired`, `cancelled`, `declined`. The list can grow: read a value you do not know as not usable yet.

## Next

> [card] [Give a key organisation wallets](https://tetrafi.mintlify.site/before-you-trade.md#give-a-key-organisation-wallets)
>
> Let a key trade from the new wallet.

> [card] [Choose wallets and accounts](https://tetrafi.mintlify.site/trade/wallets-and-accounts.md)
>
> Name the wallet a quote trades from.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.