Account linking & caps
How an assistant signs in with Swop over OAuth 2.1, what each scope allows, and the three layers that keep money safe.
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
| 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
Account linking is standard OAuth 2.1 with PKCE, so MCP clients handle it for you:
- The assistant calls a tool that needs an account without a token. The server answers
401withWWW-Authenticate: Bearer resource_metadata="https://mcp.swopme.co/.well-known/oauth-protected-resource/mcp". - The client reads that document, which names the authorization server:
https://apps.apiswop.co. - The client registers itself (dynamic client registration) and opens the authorization page.
- 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.
- 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
| 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.
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: 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
Every tool that moves money, posts publicly or adds risk runs in two calls:
- Call without
confirm. The server returns a preview (recipient, token, chain, amounts, price used, fees, caps remaining, or for agent changes asummary, a before/afterdiffand ariskNote) and apreviewId. - Show the user that preview and get an explicit yes.
- Call again with the
previewIdandconfirm: 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.
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.
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.