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

# API Keys

API keys are how AI agents and your backend services authenticate to Agent Wallet. Each key wraps a set of policies — permissions, chains, and spend limits — that ShredPay enforces on every request.

## Anatomy of a key

| Field                        | Description                                                              |
| ---------------------------- | ------------------------------------------------------------------------ |
| `key_id`                     | Stable identifier (e.g. `key_01HRZK…`). Safe to log.                     |
| `secret`                     | The `sk_live_…` or `sk_test_…` value. Sensitive. Shown once at creation. |
| `name`                       | Human label set by the creator.                                          |
| `sub_wallet_id`              | Which sub-wallet the key controls. One-to-one binding.                   |
| `permissions`                | `read` or `trade`.                                                       |
| `allowed_chains`             | List of chain IDs (e.g. `[8453, 42161]`). Empty list = all supported.    |
| `daily_limit_usd`            | USD spend cap per UTC day.                                               |
| `monthly_limit_usd`          | USD spend cap per UTC month.                                             |
| `status`                     | `active`, `revoked`, or `rotating`.                                      |
| `created_at`, `last_used_at` | Audit fields.                                                            |

## Permissions

Two levels — keep them as small as you can get away with.

| `read`  | All `GET /api/*` endpoints. MCP read tools. No signing.                    |
| ------- | -------------------------------------------------------------------------- |
| `trade` | Everything `read` does **plus** `POST /api/tx/send`, swap, DeFi, gas swap. |

## Spend limits

Spend is measured in USD using the price oracle at the time of execution. Native gas paid by ShredPay (sponsored flows) does **not** count against the key's limit. The `value` of swaps and DeFi deposits **does**.

```http
GET /api/limits
```

```json
{
  "daily_limit_usd": "1000",
  "daily_used_usd": "247.50",
  "monthly_limit_usd": "10000",
  "monthly_used_usd": "1820.00",
  "resets_at": "2026-04-26T00:00:00Z"
}
```

When a request would push usage over either cap, ShredPay returns `403 LIMIT_EXCEEDED` **before** any signing. Funds stay safe.

## Allowed chains

`allowed_chains` is an explicit whitelist. A request whose `chain_id` isn't on the list is rejected with `403 CHAIN_NOT_ALLOWED`. Use it to:

* Restrict an experimental key to a low-fee testnet-equivalent like Base.
* Stop a swap bot from accidentally moving on Mainnet.
* Implement per-chain risk budgets at the IAM layer.

## Rotating

```http
POST /api/v1/agent/keys/{key_id}/rotate
```

The response contains a fresh `secret`. The previous secret continues to authenticate for **24 hours** then is permanently retired. Use this window to deploy the new value across your fleet without downtime.

## Revoking

```http
DELETE /api/v1/agent/keys/{key_id}
```

Immediate. There is no grace period — use rotation if you need one.

## Best practices

* **One key per environment.** Test keys never authenticate against Prod and vice versa.
* **One key per agent / use case.** Easier to attribute spend, easier to revoke.
* **Read keys for dashboards, trade keys for bots.** Don't grant `trade` to anything that doesn't need to write.
* **Bind to chains.** Even if a bot only ever runs on Base, set `allowed_chains: [8453]`.
* **Set tight limits.** Start small. You can raise limits without re-issuing.
* **Rotate on a schedule.** Quarterly is a reasonable default.
* **Monitor `last_used_at`.** A key that hasn't been used in 30 days is a candidate for retirement.

## Related

* [Authentication](/developers/getting-started/authentication.md) — how to send the key
* [Sub-wallets](/developers/agent-wallet/concepts/sub-wallets.md) — what the key controls
* [Address Screening](/developers/agent-wallet/concepts/address-screening.md) — the other server-side guardrail