# Payout wallets

> List the other wallets your account has saved, so a payment link or invoice can pay one of them instead of your main payout wallet.

Source: https://railbed.com/docs/api/payout-wallets/ · Updated: 2026-11-18 · Railbed developer docs

For AI assistants: the index of every docs page, with the rules for an integration, is https://railbed.com/docs/llms.txt

## The payout wallet object

Every sale settles to your account's payout wallet. An owner can save other wallets beside it in the dashboard under [Settings → Payout wallet](https://app.railbed.io/settings), and a [payment link](https://railbed.com/docs/api/payment-links.md#create-a-payment-link) or an [invoice](https://railbed.com/docs/api/invoices.md#create-an-invoice) can pay one of them: send its id as `payout_wallet_id`. This endpoint lists those wallets, so your code can find the id without anyone copying it from the dashboard.

| Field | Type | Description |
|---|---|---|
| `id` | string | The wallet's id, `pw_…`: what `payout_wallet_id` takes |
| `object` | string | `"payout_wallet"` |
| `network` | string | `evm` for a wallet on Polygon and the other EVM networks, the kind a payment link or invoice can pay. Any other value, such as `bitcoin`, `tron` or `solana`, is a wallet for crypto payments in that network's coins |
| `address` | string | The wallet's address, in its network's own form |
| `label` | string or null | The owner's name for an `evm` wallet, such as `Wholesale`. `null` for a wallet on another network |
| `usable` | boolean | `true` when a Live payment link or invoice can pay this wallet today. `false` for a wallet on another network, and for one the wallet checks refuse; naming it in Live mode is `409 payout_wallet_unusable` |
| `created` | integer | When it was saved, in Unix seconds |

> [!NOTE]
> The API only reads wallets. Saving, changing and removing one is an owner's job in the dashboard, behind a fresh sign-in, so a key that leaks can never point your money somewhere else. Your main payout wallet isn't in this list: a payment link or invoice pays it when `payout_wallet_id` is `null` or left out.

## List payout wallets

`GET /v1/payout_wallets`

Returns every wallet your account has saved, newest first. Saved wallets aren't per mode, so a Test key and a Live key read the same list. An account keeps at most ten `evm` wallets and one for each other network, so the list comes in one page: `has_more` is always `false` and there are no parameters.

Example: cURL

```bash
curl https://pay.railbed.io/v1/payout_wallets \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
```

Example: Node\.js

```js
const { data: wallets } = await fetch('https://pay.railbed.io/v1/payout_wallets', {
  headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());
// The wallet a wholesale invoice should pay.
const wholesale = wallets.find((w) => w.label === 'Wholesale' && w.usable);
```

Example: Python

```python
wallets = requests.get(
    "https://pay.railbed.io/v1/payout_wallets",
    headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
    timeout=15,
).json()["data"]
# The wallet a wholesale invoice should pay.
wholesale = next((w for w in wallets if w["label"] == "Wholesale" and w["usable"]), None)
```

Example: Response · response 200 OK

```json
{
  "data": [
    {
      "id": "pw_Wh7kQ2nVx9RtZ4mLp6Cb",
      "object": "payout_wallet",
      "network": "evm",
      "address": "0x7a1c4e9b2d5f8a3c6e0b1d4f7a9c2e5b8d0f3a6c",
      "label": "Wholesale",
      "usable": true,
      "created": 1790380525
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

An account with no other wallets gets an empty `data`. A removed wallet leaves the list at once, and a new payment link or invoice that names it is `400 invalid_payout_wallet`.

## Access

This endpoint needs the `payments:read` [scope](https://railbed.com/docs/api.md#scopes), which every secret key has, **Read only** keys included, and connected AI agents too.
