# Account linking & caps (/docs/mcp/account-linking-and-caps)

An assistant connected to the Swop MCP starts with **no access** to anyone's account. Public tools (identity, stores, market data) work immediately. Everything personal needs the user to link their Swop account, and anything that moves money needs three separate yeses.

## The three layers [#the-three-layers]

| Layer | Who sets it | What it controls |
|---|---|---|
| **1. Scopes** | The user, on the Sign in with Swop page | Which kinds of tool the assistant may call at all |
| **2. Delegation and caps** | The user, in the Swop app under **Settings → AI assistants** | Whether AI spending is on, and per-transaction and daily limits, with separate switches for perps and swaps |
| **3. Preview, then confirm** | The user, in the chat, every time | Each money action is shown in full and runs only after an explicit yes |

All three must allow an action. A user can switch AI spending off, lower a cap or disconnect an assistant at any time, and every action an assistant takes appears in their activity like any other transaction.

## Signing in [#signing-in]

Account linking is standard **OAuth 2.1 with PKCE**, so MCP clients handle it for you:

1. The assistant calls a tool that needs an account without a token. The server answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://mcp.swopme.co/.well-known/oauth-protected-resource/mcp"`.
2. The client reads that document, which names the authorization server: `https://apps.apiswop.co`.
3. The client registers itself (dynamic client registration) and opens the authorization page.
4. The user approves on a **Sign in with Swop** page, from the Swop app or by email login. The page groups permissions into what the assistant can **view**, what it can **change**, and what can **move money**.
5. The client receives tokens and retries the call with `Authorization: Bearer …`.

| Endpoint | URL |
|---|---|
| Protected resource metadata | `https://mcp.swopme.co/.well-known/oauth-protected-resource/mcp` (and `…/mcp/commerce`) |
| Authorization server metadata | `https://apps.apiswop.co/.well-known/oauth-authorization-server` |
| Register | `POST https://apps.apiswop.co/oauth/register` |
| Authorize | `GET https://apps.apiswop.co/oauth/authorize` |
| Token | `POST https://apps.apiswop.co/oauth/token` |
| Revoke | `POST https://apps.apiswop.co/oauth/revoke` |

Clients are public (`token_endpoint_auth_method: none`) and must use PKCE with `S256`. Access tokens last one hour; refresh tokens last 90 days. One token works on both `/mcp` and `/mcp/commerce`.

## Scopes [#scopes]

| Scope | What the user is approving | Tools |
|---|---|---|
| `profile.read` | View your profile and SmartSite | Profile, help, verified prices and sports data |
| `wallet.read` | View balances, transactions, positions and orders | Balances, orders, launched tokens, prediction positions |
| `smartsite.write` | Edit your SmartSite and post to your feed (you confirm each post) | SmartSite and feed tools |
| `commerce.write` | Create and update products and payment links | Products, checkout, webhooks, embed origins |
| `wallet.trade` | Get swap quotes (and swap, within caps) | `swop_get_swap_quote`, `swop_swap` |
| `wallet.send` | Send money from your wallet, within the caps you set in the app | `swop_send`, `swop_get_spending_delegation` |
| `payments.x402` | Pay x402 payment links from your wallet, within your caps | `swop_pay_x402_link` |
| `perps.trade` | Open and close perps positions, within your margin and leverage caps | `swop_perps_order` |
| `predictions.trade` | Place, sell and cancel prediction-market orders, within your caps and agent limits | `swop_prediction_order`, `swop_cancel_prediction_order` |
| `agent.read` | View your AI trading agent: strategies, settings and activity | `swop_get_my_agent`, `swop_resolve_strategy_markets` |
| `agent.write` | Control your AI trading agent (you confirm anything that adds risk) | `swop_message_my_agent`, `swop_update_my_agent` |

The `/mcp/commerce` endpoint advertises only `profile.read`, `wallet.read`, `smartsite.write` and `commerce.write`, so its consent screen never asks for money permissions. The exact scope for every tool is listed in the [tool reference](/docs/mcp/tool-reference).

## Delegation and caps [#delegation-and-caps]

Money tools act through a **delegation**: a standing permission the user grants in the Swop app that lets AI assistants act on their wallet, within limits. An assistant can read the current settings with [`swop_get_spending_delegation`](/docs/mcp/tool-reference/money): whether it's on, the per-transaction and daily caps, and how much of today's cap is used.

- **Sends, x402 payments and swaps** count against the per-transaction and daily caps.
- **Perps** have a **margin** cap per position and a **leverage** ceiling: $25 margin at 5× controls about $125 of exposure.
- **Prediction buys** count against the caps and also obey the limits set on the user's AI trading agent. Sells and cancels reduce risk and are allowed.

When a request is over a cap or AI spending is off, the tool doesn't fail silently. For USDC on Base it returns a link to approve that one payment in the Swop app; other tokens are refused with a clear reason, and the user sends from the app or raises their caps.

Things an assistant can never do through the MCP: sign in for the user, turn AI spending on, raise caps, use cards, or move assets on Solana. Those happen in the Swop app.

## Preview, then confirm [#preview-then-confirm]

Every tool that moves money, posts publicly or adds risk runs in two calls:

1. Call **without** `confirm`. The server returns a **preview** (recipient, token, chain, amounts, price used, fees, caps remaining, or for agent changes a `summary`, a before/after `diff` and a `riskNote`) and a `previewId`.
2. Show the user that preview and get an explicit yes.
3. Call again with the `previewId` and `confirm: true`.

Previews are single-use. A confirm that describes anything different from its preview is refused, and agent-change previews expire after five minutes. Two-step tools: `swop_send`, `swop_pay_x402_link`, `swop_swap`, `swop_perps_order`, `swop_prediction_order`, `swop_create_feed_post` and the risk-adding actions of `swop_update_my_agent`.

<Callout type="warn" title="If you build your own client">
Never set `confirm: true` on the first call, and never confirm on the user's behalf. Render the preview in your UI and require a deliberate action from the user.
</Callout>

## Disconnecting [#disconnecting]

Users can disconnect any assistant from **Settings → AI assistants** in the Swop app. That revokes its grant; the next call gets a fresh `401` and sign-in prompt.
