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.

2. Open the Agent Console at 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.