> 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/getting-started/overview.md).

# Overview

A high-level look at how ShredPay is wired together and where your code fits in.

## Architecture at a glance

```
┌────────────────────┐        ┌────────────────────┐
│   Your app /       │        │   AI agent (MCP)   │
│   backend service  │        │   Claude, OpenClaw │
└─────────┬──────────┘        └─────────┬──────────┘
          │                             │
          │  REST  X-Api-Key            │  MCP  X-Api-Key
          │  https://agent-api...       │  /mcp endpoint
          ▼                             ▼
┌──────────────────────────────────────────────────┐
│             Agent Service (public)                │
│   API key auth · spend limits · screening         │
│   tx orchestration · MCP transport                │
└────────┬─────────────┬───────────────┬────────────┘
         │             │               │
         ▼             ▼               ▼
   Wallet Service  Screening     Router contracts
   (sub-wallets,   Service       (on-chain swap +
    P-256 quorum)  (OFAC, risk)   DeFi, gas sponsor)
```

## Request lifecycle (write path)

When an agent calls `POST /api/tx/send`:

1. **Authenticate** — Agent Service resolves the `X-Api-Key` to a sub-wallet and checks the key's permissions and `allowed_chains`.
2. **Limit check** — Daily and monthly USD spend is rolled up against the key's caps.
3. **Screen** — The `to` address (and any beneficiaries decoded from calldata) are screened.
4. **Co-sign** — Agent Service co-signs with its P-256 key; Privy signs with the user-side key (2/2 quorum).
5. **Broadcast** — The transaction is submitted to the configured RPC for the chain.
6. **Webhook** — When the tx confirms (or fails), Agent Service emits an event to your registered webhook URL.

Read-only requests (`get_balance`, `get_positions`, etc.) skip steps 2–5.

## Two ways to integrate

| Path                | When to use                                                                         | Auth               |
| ------------------- | ----------------------------------------------------------------------------------- | ------------------ |
| **REST** (`/api/*`) | Backends, traditional apps, deterministic flows.                                    | `X-Api-Key` header |
| **MCP** (`/mcp`)    | LLM agents that should pick the right tool autonomously (Claude, OpenClaw, custom). | `X-Api-Key` header |

The two surfaces are equivalent — every MCP tool maps 1:1 to a REST endpoint.

## What you need before building

1. A ShredPay account — sign up at [shredpay.xyz](https://shredpay.xyz).
2. Open the **Agent Console** at [console.shredpay.xyz](https://console.shredpay.xyz) and create a sub-wallet.
3. Issue an API key with the limits and chains you want to allow.
4. Fund the sub-wallet (USDC + a small ETH balance, or use the gas swap flow).

You're ready. Continue to [Authentication](/developers/getting-started/authentication.md).