# 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](/getting-started/authentication.md).


---

# Agent Instructions: 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:

```
GET https://developers.shredpay.xyz/getting-started/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.