> For the complete documentation index, see [llms.txt](https://developers.shredpay.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.shredpay.xyz/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](/getting-started/authentication.md) — how to send the key
* [Sub-wallets](/agent-wallet/concepts/sub-wallets.md) — what the key controls
* [Address Screening](/agent-wallet/concepts/address-screening.md) — the other server-side guardrail


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.shredpay.xyz/agent-wallet/concepts/api-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.