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

# Create a multi-chain wallet with the Yara API

> Create a Yara wallet, store its stable ID, use provisioned receive addresses across supported chains, and safely retry requests with idempotency.

Create a wallet whenever you need a stable receiving identity for your business or one of your customers. Store the returned wallet `id`; it stays the same across all of the wallet's chain-specific destinations.

## Create the wallet

Send a `POST` to `/v1/wallets`. Do not choose a chain. Yara provisions every supported deposit chain automatically.

```bash theme={null}
curl https://api.yara.cash/v1/wallets \
  --request POST \
  --header "x-yara-api-key: $YARA_API_KEY" \
  --header "X-Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "Customer receipts",
    "customer_id": "5ec10df5-acde-4e95-926c-2174279cf2fd"
  }'
```

Both fields are optional. Use `label` to identify the wallet in your own workflow. Add `customer_id` when deposits to the wallet should be attributed to one of your Yara customers.

### Response

```json theme={null}
{
  "status": "success",
  "message": "wallet created",
  "error": "",
  "data": {
    "id": "7f7c6713-3fdc-43fb-a9e7-d3c364e7c763",
    "merchant_id": "8fca3c8d-5d48-4f4d-a286-2ef6d1cd2f01",
    "customer_id": "5ec10df5-acde-4e95-926c-2174279cf2fd",
    "label": "Customer receipts",
    "status": "ACTIVE",
    "destinations": [
      {
        "id": "ea38c60e-7a0b-44f6-bdf0-8ec13a7e471a",
        "chain": "BASE",
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "status": "ACTIVE"
      },
      {
        "id": "af85c3af-d88b-47b5-8bf2-d50bc722251c",
        "chain": "SOLANA",
        "address": "4Nd1mYB5F9A5R3rzU7V1nv5A22iZ8bWC",
        "status": "ACTIVE"
      },
      {
        "id": "ce0bcbce-3708-4f67-86ae-3d720e9a87fc",
        "chain": "BITCOIN",
        "address": "bc1qyaraexample8f0d9w3j",
        "status": "ACTIVE"
      }
    ],
    "created_at": "2026-08-17T10:00:00Z",
    "updated_at": "2026-08-17T10:00:02Z"
  }
}
```

The example shows a subset of the destinations for readability. The response contains one destination for every supported deposit chain.

## Provisioning statuses

A wallet can be `PROVISIONING`, `ACTIVE`, `PARTIALLY_ACTIVE`, `FAILED`, `FROZEN`, or `DISABLED`. Each destination also has its own status.

You can begin using an `ACTIVE` destination immediately. If one destination cannot be provisioned immediately, it may be `FAILED` while the wallet is `PARTIALLY_ACTIVE`. Yara retries failed provisioning, so fetch the wallet again before presenting that destination to a sender.

## Which chains can I use?

Fetch the live list from [`GET /v1/chains`](/wallets/api-reference/overview). Each entry tells you the supported `assets` and whether `deposit_enabled` is `true`.

```bash theme={null}
curl https://api.yara.cash/v1/chains \
  --header "x-yara-api-key: $YARA_API_KEY"
```

## List and fetch wallets

List wallets, optionally filtering by customer, destination chain, status, label, address, or wallet ID:

```bash theme={null}
curl "https://api.yara.cash/v1/wallets?customer_id=5ec10df5-acde-4e95-926c-2174279cf2fd&limit=50" \
  --header "x-yara-api-key: $YARA_API_KEY"
```

Or fetch one wallet and all of its destinations:

```bash theme={null}
curl https://api.yara.cash/v1/wallets/7f7c6713-3fdc-43fb-a9e7-d3c364e7c763 \
  --header "x-yara-api-key: $YARA_API_KEY"
```

<Tip>
  Reuse the same idempotency key when retrying a failed create request so you don't create another wallet.
</Tip>

## Next

<CardGroup cols={2}>
  <Card title="Receive funds" icon="arrow-down-to-bracket" href="/wallets/guides/receive-funds">
    Select a destination and get notified when deposits arrive.
  </Card>

  <Card title="Whitelist a recipient" icon="shield-check" href="/wallets/guides/whitelist-an-address">
    Approve a destination before paying out.
  </Card>
</CardGroup>