> For the complete documentation index, see [llms.txt](https://docs.madhousewallet.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madhousewallet.com/quickstart/api-keys.md).

# API Keys

Creating and securing your API credentials

API keys are the credential used to authenticate all requests to the Madhouse Wallet off-ramp API.

***

## Key Format

```
mw_live_<keyId>_<secret>
```

* `keyId` — 8-character identifier visible in the dashboard
* `secret` — 32-character hex string (128-bit entropy)

The full key is shown **once** at creation. It is stored as a SHA-256 hash server-side and cannot be retrieved again. If lost, revoke the key and create a new one.

***

## Creating a Key

1. Sign in at [business.madhousewallet.com](https://business.madhousewallet.com)
2. Go to **Developers → API Keys**
3. Click **Create Key**
4. Optionally name the key (e.g. `production`, `staging`)
5. Copy the full key — it will not be shown again

Up to **5 keys** per account. Each key has independent rate limits and last-used tracking.

***

## Using a Key

Include the key in the `Authorization` header on every request:

```bash
curl https://business.madhousewallet.com/api/payouts/quote \
  -H "Authorization: Bearer mw_live_xxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -G -d "targetCurrency=NGN" -d "sourceAmount=500"
```

***

## IP Restriction

Lock a key to a specific IPv4 address to prevent use from any other origin.

1. In the dashboard go to **Developers → Settings**
2. Enter your server's public IPv4 address
3. Save — restriction takes effect immediately

Requests from any other IP will receive `403 Forbidden`.

To update the allowed IP, replace it in settings. An admin can also force-enable IP restriction on your account — in that case you cannot disable it, only change which IP is allowed.

***

## Rate Limits

Limits are **per key** (not per account). A second key gets a second set of quotas.

| Endpoint                  | Limit         |
| ------------------------- | ------------- |
| Account requirements      | 60 req/min    |
| Quote                     | 20 req/min    |
| Transfer (create)         | 5 req/min     |
| Transfer (cancel, status) | 20–30 req/min |
| Recipients                | 30 req/min    |

Rate limit headers on every response:

```
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1743254460
```

***

## Revoking a Key

Go to **Developers → API Keys**, find the key, and click **Revoke**. Revocation is immediate — any in-flight request using that key will fail with `401`. Create a new key to replace it.

***

## Security Best Practices

* Store keys in environment variables or a secrets manager — never in source code
* Use one key per environment (`prod`, `staging`, `dev`)
* Enable IP restriction on production keys
* Rotate keys periodically; revoke any key that may have been exposed
* Monitor `lastUsedAt` in the dashboard for unexpected activity