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

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:

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