Build with AI

An agent that integrates Soroswap needs three things: the docs, the rules of the API, and a way to check its work. This page gives it all three. Everything here is free and read-only unless it says otherwise.

Resource	URL	Use it for
Docs MCP	`https://docs.soroswap.finance/mcp`	Search and read these docs and the OpenAPI from your editor. No auth
`llms.txt`	docs.soroswap.finance/llms.txt	One-fetch index of every page, with the API essentials at the top
`llms-full.txt`	docs.soroswap.finance/llms-full.txt	Every page in one file, for a RAG pipeline or a long context
Markdown of any page	Append `.md` to its URL, for example /api/quickstart.md	Small, exact fetches. `Accept: text/markdown` works too
OpenAPI	api.soroswap.finance/api-json	Request and response schemas, for code generation
Skill	docs.soroswap.finance/skill.md	What the API does, the intent router, errors and gotchas, in one file

Connect the docs MCP

The docs MCP is read-only: it searches and reads documentation, it does not call the API.

claude mcp add --transport http soroswap-docs https://docs.soroswap.finance/mcp

Check it with claude mcp list. To share it with your team, put it in the project’s .mcp.json instead:

{
  "mcpServers": {
    "soroswap-docs": {
      "type": "http",
      "url": "https://docs.soroswap.finance/mcp"
    }
  }
}

Add it to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "soroswap-docs": {
      "url": "https://docs.soroswap.finance/mcp"
    }
  }
}

Every page of these docs also has a Connect to Cursor entry in its page menu.

Open Windsurf: Configure MCP Servers from the command palette and add it to mcp_config.json. Windsurf uses serverUrl, not url:

{
  "mcpServers": {
    "soroswap-docs": {
      "serverUrl": "https://docs.soroswap.finance/mcp"
    }
  }
}

codex mcp add soroswap-docs --url https://docs.soroswap.finance/mcp

Or in ~/.codex/config.toml:

[mcp_servers.soroswap-docs]
url = "https://docs.soroswap.finance/mcp"

Add it to .vscode/mcp.json:

{
  "servers": {
    "soroswap-docs": {
      "type": "http",
      "url": "https://docs.soroswap.finance/mcp"
    }
  }
}

Every page of these docs also has a Connect to VS Code entry in its page menu.

Open Settings, Connectors and choose Add custom connector.
Name it Soroswap Docs and set the URL to https://docs.soroswap.finance/mcp.
In a chat, enable it from the tools menu.

Any other MCP client connects to the same URL over Streamable HTTP.

Install the skill

The skill teaches a local agent (Claude Code, Codex, Cursor) when to use which endpoint, the errors to expect and the Stellar gotchas, so it writes a correct integration on the first try.

npx skills add https://docs.soroswap.finance

It installs skill.md, the skill these docs publish. It tells the agent that a page it fetched from these docs wins over what the skill remembers.

Rolling out. The sections below describe the next tools for agents. They are not live yet: until each one ships, its command fails. Use the docs MCP and the skill above in the meantime.

The skills repository

A set of focused skills (API integration, calling the aggregator from a contract, AMM liquidity), with runnable examples, installable in one command:

npx skills add soroswap/agent-skills

Let the agent call the API: the trading MCP

The trading MCP lets an agent quote, build and submit swaps through the Aggregator API. It runs inside the API at https://api.soroswap.finance/mcp.

It never signs. Tools that build a transaction return unsigned XDR. Your wallet or your signer signs it, and only then can the agent submit it.
Your key passes through. Send the same Authorization: Bearer sk_... header the REST API takes. The MCP uses it for that request and does not store it.

claude mcp add --transport http soroswap https://api.soroswap.finance/mcp \
  --header "Authorization: Bearer $SOROSWAP_API_KEY"

In Cursor, VS Code or Windsurf, add the same URL with a headers object: "headers": { "Authorization": "Bearer sk_..." }. In Codex, set bearer_token_env_var = "SOROSWAP_API_KEY" under [mcp_servers.soroswap].

Let the agent use a terminal: the CLI

The @soroswap/sdk package ships a soroswap command for agents with a shell and for bots: no prompts, JSON output, and signing as a separate step.

npx -p @soroswap/sdk soroswap --help

Rules for your repository’s agent

Paste this into the AGENTS.md or CLAUDE.md of the repository where you integrate Soroswap. It keeps the agent on the rules that matter even when it has not read these docs.

## Soroswap Aggregator API

- Docs: https://docs.soroswap.finance (append .md to any page). Index: https://docs.soroswap.finance/llms.txt
- Base URL: https://api.soroswap.finance. Always send ?network=mainnet or ?network=testnet;
  leaving it out means mainnet.
- Auth: `Authorization: Bearer $SOROSWAP_API_KEY` (starts with sk_). Server side only, never in
  frontend code. A missing or bad key returns 403, not 401.
- Flow: POST /quote -> POST /quote/build with the quote unchanged and `from` -> user signs ->
  POST /send (or your own RPC). Always quote before you build, and build right before signing:
  a Soroban XDR is valid for 180 seconds.
- Submit the built XDR as is. Do not re-simulate it or call prepareTransaction on it.
- Assets are contract addresses (C...), never CODE:ISSUER. Amounts are integer strings in the
  asset's smallest unit: XLM, USDC and every classic asset have 7 decimals, so 1 USDC = "10000000".
  Read decimals from the asset list for Soroban tokens.
- `protocols` must list the venues: ["soroswap","aqua","sushi","comet","sdex"]. Leave out sdex
  when you execute from a contract or a smart wallet.
- Branch on the quote's `platform` (aggregator, router, sdex) before executing.
- 428 CREATE_TRUSTLINE: sign and submit actionData.xdr, then build again. 409: quote again.
  429: wait Retry-After. 503: retry with backoff. Never retry a 400 unchanged.
- Test on testnet first (?network=testnet, Friendbot, https://faucet.soroswap.finance).
  Never submit to mainnet without the user's explicit confirmation.

Prompts and the calls they should produce

A correct agent turns each prompt into the calls on its right. We use this table as our own eval: each prompt runs in a fresh session with only the docs MCP and the skill installed, and passes when the agent makes these calls, in this order, with the right units.

Prompt	Expected sequence	Must not
”Swap 100 USDC to XLM for `G...`”	`POST /quote` (`assetIn` USDC `C...`, `amount: "1000000000"`, `EXACT_IN`, all venues) → `POST /quote/build` (`quote`, `from`) → sign → `POST /send`	Send `"100"` or `100.0` as the amount
”Buy exactly 50 USDC with XLM”	`POST /quote` (`tradeType: "EXACT_OUT"`, `amount: "500000000"`) → `/quote/build` → sign → `/send`	Quote `EXACT_IN` and hope
”How much XLM do I get for 10 USDC?”	`POST /quote` with no wallet, report `amountOut` ÷ 10^7	Build or ask for a signature
”What is XLM worth in USD?”	`GET /price?network=mainnet&asset=CAS3...&referenceCurrency=USD`	Divide `price` by 10^7
”Show the balances of `G...`”	`GET /balances/{address}?network=mainnet`, report `amount` / `available`	Read `rawAmount` as whole units
”Swap XLM to EURC for a wallet that never held EURC”	`/quote` → `/quote/build` returns 428 → sign and submit `actionData.xdr` → `/quote/build` again → sign → `/send`	Treat the 428 as a failure
”Let a user with no XLM receive USDC”	`/quote` with `gaslessTrustline: "create"` and `sdex` in `protocols` → `/quote/build` with `sponsor` → user and sponsor sign → `/send`	Use it when the user already has the trustline
”Which venues can you route through?”	`GET /protocols?network=mainnet`	Hard-code a list
”Charge my users 0.5% on swaps”	`GET /partner` → `PUT /partner/rate` with `{"partnerBps": 50}` (the account must already be a partner, see Fees)	Put `feeBps` in the quote body, which is ignored
”Execute the best route from my Soroban contract”	`/quote` without `sdex` → pass `rawTrade.distribution` to the aggregator’s `swap_exact_in`	Call `/quote/build` with a `C...` address
”Test a swap on testnet”	Friendbot → `/quote?network=testnet` with `protocols: ["soroswap"]` and testnet addresses → `/quote/build` → sign → `/send?network=testnet`	Reuse mainnet contract addresses
”Add liquidity to the XLM/USDC pool”	`GET /pools/{tokenA}/{tokenB}?network=mainnet&protocol=soroswap` for the ratio → `POST /liquidity/add` → sign → `/send`	Pick `amountB` off the pool ratio

When an agent gets something wrong

Most first-try failures come from units, asset addresses, an expired build or a missing trustline. Stellar gotchas lists each one with the exact error, and Errors says which ones to retry. If these docs led your agent astray, tell us from the docs MCP (it has a feedback tool) or on Discord.

Get started

Guides

Execute from your own contract

Monetize

Production

Connect the docs MCP

Install the skill

The skills repository

Let the agent call the API: the trading MCP

Let the agent use a terminal: the CLI

Rules for your repository’s agent

Prompts and the calls they should produce

When an agent gets something wrong

​Connect the docs MCP

​Install the skill

​The skills repository

​Let the agent call the API: the trading MCP

​Let the agent use a terminal: the CLI

​Rules for your repository’s agent

​Prompts and the calls they should produce

​When an agent gets something wrong

Connect the docs MCP

Install the skill

The skills repository

Let the agent call the API: the trading MCP

Let the agent use a terminal: the CLI

Rules for your repository’s agent

Prompts and the calls they should produce

When an agent gets something wrong