DevelopersAPI · MCP · Docs
Build on Swaps.
API, MCP server and docs for your product or your agent.
API key
ExampleName
Production server
Live key ending 9f2K
- Scopes
- payment_links.write
capabilities.read - Swaps-Version
- 2026-09-04
One request
One request.
Three ways in.
Create the same payment link from a terminal, from your code or from your agent. The container changes. The request does not.
curl https://api.swaps.app/v1/payment_links \
-H "x-api-key: $SWAPS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"title": "Brand design, Project 08","amount": { "amount": "85000", "currency": "USD", "decimals": 2}
}'
201 CreatedA payment_link in status draft.
const url = "https://api.swaps.app/v1/payment_links";
const res = await fetch(url, {
method: "POST",
headers: {
"x-api-key": process.env.SWAPS_API_KEY!,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"title": "Brand design, Project 08","amount": { "amount": "85000", "currency": "USD", "decimals": 2}
}),
});
const link = await res.json(); // link.status: "draft"
201 CreatedThe same draft, typed in your code.
POST https://mcp.agent.swaps.app/mcp
Authorization: Bearer $SWAPS_API_KEY
{
"jsonrpc": "2.0", "id": 1,
"method": "tools/call",
"params": {
"name": "create_payment_request",
"arguments": {
"title": "Brand design, Project 08","amount": { "amount": "85000", "currency": "USD", "decimals": 2}
}
}
}
Tool resultA draft, plus a link the merchant opens to confirm it.
A new link is a draft. Nothing is charged until it is activated.
Resources
Everything is a resource.
One REST surface at api.swaps.app/v1. The Swaps dashboard uses the same resources you do.
Bank-service provider
Bank rails run through Bridge and its banking partners. capabilities shows which rails are live for your account.
- Payment links
- payment_links
- clients
- products
- payments
- Pay an invoice
- payouts
- payroll_runs
- payroll_recipients
- payroll_templates
- wallet/balances
- wallet/transactions
- wallet/conversions
- Buy and sell
- quotes
- orders
- capabilities
- Screening
- screenings
- traces
- transactions
- Keys and events
- api_keys
- webhook_endpoints
- events
Conventions: keys, test mode, idempotency, versions, money, errors
Keys and scopes
Send your key in x-api-key. Each key holds only the scopes you give it.
payment_links.writeTest mode
Test keys start with sk_test_. A test call runs on test data or is refused. It never reaches live money. In the dashboard, most money screens are not available in test mode.
sk_test_…Idempotency
Every write carries a key you generate. A retry within 24 hours returns the first response.
Idempotency-KeyVersions
Pin behaviour to a dated version. Every response echoes the one it used.
Swaps-Version: 2026-09-04Money
An amount is a minor-unit string with its currency and decimals. Never a float.
"85000" · USD · 2Errors
One envelope: type, code, message, doc_url. A 429 says how long to wait.
Retry-After
Events and agents
Events, signed.
Subscribe an https endpoint to the events you need, or stream them from /v1/events/stream. Every delivery is signed with Swaps-Signature.
- payment_link.paid
- payment_link.settled
- payment.underpaid
- payout.created
- payroll_run.completed
- order.status_changed
- customer.verification_state_changed
- test.ping
Delivered at least once. Deduplicate on the event id.
Agents, same rules.
A hosted MCP server over HTTP. Your agent signs in with your business key and gets tools, not endpoints.
https://mcp.agent.swaps.app/mcp
- list_capabilities
- get_quote
- create_payment_request
- check_payment_request
- prepare_invoice_payout
- prepare_payroll_run
- get_wallet_balance
- check_address_risk
Tools read, price and prepare. A person confirms every money step.
Public MCP · read-only
One call.
A real answer.
Ask our public MCP server for its tools, from your browser. No key. Nothing changes.
POST /api/mcp-public
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
Example200 · 6 tools, all read-only
- swaps_wallet_inspect
- swaps_search_preview
- swaps_report_fetch
- swaps_report_render
- swaps_taxonomy
- swaps_corridors
Raw answer Example
{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"swaps_wallet_inspect","title":"Inspect wallet or transaction in Swaps","description":"Primary public Swaps Search tool. Use this first for wallet risk, transaction explanation, and trace requests so ChatGPT shows the Swaps intelligence widget instead of a text-only preview. Call it without pre-tool narration. This tool is read-only and does not provide crypto execution, payment flows, or account commerce.","inputSchema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Natural-language wallet, transaction, or trace inspection request."},"intent":{"type":"string","enum":["address_check","transaction_explain","trace","route","general"],"default":"general"},"address":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"transactionHash":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"chain":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"assetSymbol":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}],"description":"Optional token or native asset scope, for example USDT, USDC, ETH, or BTC."},"asset":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]}},"required":["query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"},"securitySchemes":[{"type":"noauth"}],"_meta":{"securitySchemes":[{"type":"noauth"}],"ui":{"resourceUri":"ui://swaps/report/full.html"},"openai/outputTemplate":"ui://swaps/report/full.html","openai/toolInvocation/invoking":"Inspecting with Swaps","openai/toolInvocation/invoked":"Swaps inspection ready"},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"report"},"status":{"type":"string","enum":["complete","partial","needs_input","unsupported","auth_required","payment_required","unavailable_in_public_review","error"]},"title":{"type":"string"},"summary":{"type":"string"},"verdict":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"summary":{"type":"string"}},"required":["code","label","summary"],"additionalProperties":false},"responseGuidance":{"type":"object","properties":{"userVisibleAnswer":{"type":"string"},"useVerbatim":{"type":"boolean","const":true},"tone":{"type":"string","const":"professional_plain"},"rules":{"type":"array","items":{"type":"string"}}},"required":["userVisibleAnswer","useVerbatim","tone","rules"],"additionalProperties":false},"risk":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high","critical","unknown"]},"score":{"type":["number","null"]},"summary":{"type":"string"}},"required":["level","score","summary"],"additionalProperties":false},"report":{"type":"object","additionalProperties":{}},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["available","partial","unavailable"]},"summary":{"type":"string"},"count":{"type":["number","null"]}},"required":["id","title","status","summary"],"additionalProperties":false}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["source","flag","transaction","address","provider","quote"]},"url":{"type":["string","null"]},"confidence":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]}},"required":["label","type"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["open_link","call_tool","authenticate","required_input"]},"requiresConfirmation":{"type":"boolean"},"url":{"type":"string"},"tool":{"type":"string"}},"required":["id","label","type","requiresConfirmation"],"additionalProperties":false}},"requestId":{"type":"string"},"widget":{"type":"object","properties":{"resourceUri":{"type":"string"},"mode":{"type":"string","const":"full_report"}},"required":["resourceUri","mode"],"additionalProperties":false}},"required":["id","type","status","title","summary","verdict","risk","report","sections","sources","limitations","nextActions","requestId","widget"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"swaps_search_preview","title":"Preview Swaps Search intelligence","description":"Compatibility alias for public, read-only wallet, transaction, and trace previews. Prefer swaps_wallet_inspect for new calls. If this tool is selected, it still renders the Swaps intelligence widget. Call it without pre-tool narration. It does not provide crypto execution, payment flows, or account commerce.","inputSchema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Natural-language wallet, transaction, trace, or route request."},"address":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"transactionHash":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"chain":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"assetSymbol":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}],"description":"Optional token or native asset scope, for example USDT, USDC, ETH, or BTC."},"asset":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]}},"required":["query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"},"securitySchemes":[{"type":"noauth"}],"_meta":{"securitySchemes":[{"type":"noauth"}],"ui":{"resourceUri":"ui://swaps/report/full.html"},"openai/outputTemplate":"ui://swaps/report/full.html","openai/toolInvocation/invoking":"Inspecting with Swaps","openai/toolInvocation/invoked":"Swaps inspection ready"},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"report"},"status":{"type":"string","enum":["complete","partial","needs_input","unsupported","auth_required","payment_required","unavailable_in_public_review","error"]},"title":{"type":"string"},"summary":{"type":"string"},"verdict":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"summary":{"type":"string"}},"required":["code","label","summary"],"additionalProperties":false},"responseGuidance":{"type":"object","properties":{"userVisibleAnswer":{"type":"string"},"useVerbatim":{"type":"boolean","const":true},"tone":{"type":"string","const":"professional_plain"},"rules":{"type":"array","items":{"type":"string"}}},"required":["userVisibleAnswer","useVerbatim","tone","rules"],"additionalProperties":false},"risk":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high","critical","unknown"]},"score":{"type":["number","null"]},"summary":{"type":"string"}},"required":["level","score","summary"],"additionalProperties":false},"report":{"type":"object","additionalProperties":{}},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["available","partial","unavailable"]},"summary":{"type":"string"},"count":{"type":["number","null"]}},"required":["id","title","status","summary"],"additionalProperties":false}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["source","flag","transaction","address","provider","quote"]},"url":{"type":["string","null"]},"confidence":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]}},"required":["label","type"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["open_link","call_tool","authenticate","required_input"]},"requiresConfirmation":{"type":"boolean"},"url":{"type":"string"},"tool":{"type":"string"}},"required":["id","label","type","requiresConfirmation"],"additionalProperties":false}},"requestId":{"type":"string"},"widget":{"type":"object","properties":{"resourceUri":{"type":"string"},"mode":{"type":"string","const":"full_report"}},"required":["resourceUri","mode"],"additionalProperties":false}},"required":["id","type","status","title","summary","verdict","risk","report","sections","sources","limitations","nextActions","requestId","widget"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"swaps_report_fetch","title":"Fetch Swaps full report","description":"Use this to fetch a public review-safe Swaps Search full report for an address. It does not execute crypto transactions, start payment flows, or offer account commerce. When responding to the user, use the returned summary verbatim; do not add jokes, idioms, slang, playful translations, or metaphors.","inputSchema":{"type":"object","properties":{"id":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"address":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"chain":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"assetSymbol":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"asset":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"forceRefresh":{"type":"boolean","default":false}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"execution":{"taskSupport":"forbidden"},"securitySchemes":[{"type":"noauth"}],"_meta":{"securitySchemes":[{"type":"noauth"}]},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"report"},"status":{"type":"string","enum":["complete","partial","needs_input","unsupported","auth_required","payment_required","unavailable_in_public_review","error"]},"title":{"type":"string"},"summary":{"type":"string"},"verdict":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"summary":{"type":"string"}},"required":["code","label","summary"],"additionalProperties":false},"responseGuidance":{"type":"object","properties":{"userVisibleAnswer":{"type":"string"},"useVerbatim":{"type":"boolean","const":true},"tone":{"type":"string","const":"professional_plain"},"rules":{"type":"array","items":{"type":"string"}}},"required":["userVisibleAnswer","useVerbatim","tone","rules"],"additionalProperties":false},"risk":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high","critical","unknown"]},"score":{"type":["number","null"]},"summary":{"type":"string"}},"required":["level","score","summary"],"additionalProperties":false},"report":{"type":"object","additionalProperties":{}},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["available","partial","unavailable"]},"summary":{"type":"string"},"count":{"type":["number","null"]}},"required":["id","title","status","summary"],"additionalProperties":false}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["source","flag","transaction","address","provider","quote"]},"url":{"type":["string","null"]},"confidence":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]}},"required":["label","type"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["open_link","call_tool","authenticate","required_input"]},"requiresConfirmation":{"type":"boolean"},"url":{"type":"string"},"tool":{"type":"string"}},"required":["id","label","type","requiresConfirmation"],"additionalProperties":false}},"requestId":{"type":"string"}},"required":["id","type","status","title","summary","verdict","risk","report","sections","sources","limitations","nextActions","requestId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"swaps_report_render","title":"Render Swaps full report","description":"Render a fetched Swaps Search report as a ChatGPT widget. Call swaps_report_fetch first when report data is not already available.","inputSchema":{"type":"object","properties":{"id":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"address":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"chain":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"assetSymbol":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"asset":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"report":{"anyOf":[{"anyOf":[{"not":{}},{"type":"object","additionalProperties":{}}]},{"type":"null"}]}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"execution":{"taskSupport":"forbidden"},"securitySchemes":[{"type":"noauth"}],"_meta":{"securitySchemes":[{"type":"noauth"}],"ui":{"resourceUri":"ui://swaps/report/full.html"},"openai/outputTemplate":"ui://swaps/report/full.html","openai/toolInvocation/invoking":"Rendering Swaps report","openai/toolInvocation/invoked":"Swaps report ready"},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"report"},"status":{"type":"string","enum":["complete","partial","needs_input","unsupported","auth_required","payment_required","unavailable_in_public_review","error"]},"title":{"type":"string"},"summary":{"type":"string"},"verdict":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"summary":{"type":"string"}},"required":["code","label","summary"],"additionalProperties":false},"responseGuidance":{"type":"object","properties":{"userVisibleAnswer":{"type":"string"},"useVerbatim":{"type":"boolean","const":true},"tone":{"type":"string","const":"professional_plain"},"rules":{"type":"array","items":{"type":"string"}}},"required":["userVisibleAnswer","useVerbatim","tone","rules"],"additionalProperties":false},"risk":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high","critical","unknown"]},"score":{"type":["number","null"]},"summary":{"type":"string"}},"required":["level","score","summary"],"additionalProperties":false},"report":{"type":"object","additionalProperties":{}},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["available","partial","unavailable"]},"summary":{"type":"string"},"count":{"type":["number","null"]}},"required":["id","title","status","summary"],"additionalProperties":false}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["source","flag","transaction","address","provider","quote"]},"url":{"type":["string","null"]},"confidence":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]}},"required":["label","type"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["open_link","call_tool","authenticate","required_input"]},"requiresConfirmation":{"type":"boolean"},"url":{"type":"string"},"tool":{"type":"string"}},"required":["id","label","type","requiresConfirmation"],"additionalProperties":false}},"requestId":{"type":"string"},"widget":{"type":"object","properties":{"resourceUri":{"type":"string"},"mode":{"type":"string","const":"full_report"}},"required":["resourceUri","mode"],"additionalProperties":false}},"required":["id","type","status","title","summary","verdict","risk","report","sections","sources","limitations","nextActions","requestId","widget"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"swaps_taxonomy","title":"Get Swaps taxonomy","description":"Use this to read the Swaps taxonomy for risk and route-context reasoning.","inputSchema":{"type":"object","properties":{},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"},"securitySchemes":[{"type":"noauth"}],"_meta":{"securitySchemes":[{"type":"noauth"}]},"outputSchema":{"type":"object","properties":{"result":{"type":"object","additionalProperties":{}},"requestId":{"type":"string"}},"required":["result","requestId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"swaps_corridors","title":"Get Swaps route corridors","description":"Use this to read curated Swaps route-support corridors as context. Public ChatGPT V2 stays read-only.","inputSchema":{"type":"object","properties":{},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"},"securitySchemes":[{"type":"noauth"}],"_meta":{"securitySchemes":[{"type":"noauth"}]},"outputSchema":{"type":"object","properties":{"result":{"type":"object","additionalProperties":{}},"requestId":{"type":"string"}},"required":["result","requestId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}]}}FAQ
Questions.
Is the /v1 API available?
The /v1 API is live. Available operations depend on the resource, your key scopes and your account capabilities. Check the documentation and capabilities before you integrate.
How do I get an API key?
Sign in and open Developers in your dashboard. If access is not yet enabled for your account, request access there. Existing valid keys are not disabled by the invitation requirement. Once you have access, create a key under API keys; its secret is shown once.
Can an agent move money on its own?
No. Tools read state, price routes and prepare money movement. Every money step needs a person’s own confirmation, and some steps, like activating a link, only a person can take.
How do I know a webhook came from Swaps?
Every delivery is signed with Swaps-Signature. Verify the signature over the raw body before you parse it. Deliveries arrive at least once, so deduplicate on the event id.
Is there an SDK?
Not yet. Use curl or plain fetch today. The docs describe every field.
Can I run the MCP server locally?
Yes. The npm package @agent.swaps/mcp-server runs over stdio with read-only tools. It is separate from the hosted server.
Start with
a key.
Read the docs. Then create your first draft link.