DevelopersAPI · MCP · Docs

Build on Swaps.

API, MCP server and docs for your product or your agent.

Read the docs Get API keys

API key

Example

Name

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.

curlTerminalExample


            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.

TypeScriptcreate-link.tsExample


            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.

MCPAgent · tools/callExample


            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.write
Test 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-Key
Versions
Pin behaviour to a dated version. Every response echoes the one it used.
Swaps-Version: 2026-09-04
Money
An amount is a minor-unit string with its currency and decimals. Never a float.
"85000" · USD · 2
Errors
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.

FAQ

Questions.

When does the /v1 API open?

Together with the new Swaps dashboard. Until then, calls return 503 temporarily_unavailable.

How do I get an API key?

Sign up, then open Developers → API keys in your dashboard. The secret is shown once. If you lose it, roll the key and use the new one.

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.

Get API keys Read the docs