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.

GET /api/limits

{
  "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

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

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 — how to send the key

• Sub-wallets — what the key controls

• Address Screening — the other server-side guardrail