> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soroswap.finance/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Soroswap Aggregator API: base URL https://api.soroswap.finance, pick the network with ?network=mainnet or ?network=testnet (omitted means mainnet).
> Auth: Authorization: Bearer sk_... on every call. Get a key at https://api.soroswap.finance/register. A missing or invalid key returns 403, never 401. Free plan 1 request/s; see https://docs.soroswap.finance/api/plans.md.
> Flow: POST /quote (assetIn, assetOut as C... contract addresses, amount as an integer string in the smallest unit, tradeType, protocols) -> POST /quote/build with the unchanged quote and from -> the user signs the XDR -> POST /send. Build right after quoting: a Soroban XDR is valid for 180 seconds. Submit it as is, never re-simulate it.
> AI tools: docs MCP at https://docs.soroswap.finance/mcp (claude mcp add --transport http soroswap-docs https://docs.soroswap.finance/mcp), skill with npx skills add https://docs.soroswap.finance. Other clients: https://docs.soroswap.finance/api/build-with-ai.md.
> Units and Stellar pitfalls: https://docs.soroswap.finance/api/stellar-gotchas.md. Errors and retries: https://docs.soroswap.finance/api/errors.md.

# Build with AI

> Connect Claude Code, Cursor, Codex, Windsurf, VS Code or Claude.ai to the Soroswap docs MCP (https://docs.soroswap.finance/mcp, no auth), install the skill, and give your agent the rules for quote, build, sign and send.

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](https://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](https://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](https://docs.soroswap.finance/api/quickstart.md) | Small, exact fetches. `Accept: text/markdown` works too |
| OpenAPI | [api.soroswap.finance/api-json](https://api.soroswap.finance/api-json) | Request and response schemas, for code generation |
| Skill | [docs.soroswap.finance/skill.md](https://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 Code**

```bash theme={null}
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:

```json theme={null}
{
  "mcpServers": {
    "soroswap-docs": {
      "type": "http",
      "url": "https://docs.soroswap.finance/mcp"
    }
  }
}
```

**Cursor**

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

```json theme={null}
{
  "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.

**Windsurf**

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

```json theme={null}
{
  "mcpServers": {
    "soroswap-docs": {
      "serverUrl": "https://docs.soroswap.finance/mcp"
    }
  }
}
```

**Codex**

```bash theme={null}
codex mcp add soroswap-docs --url https://docs.soroswap.finance/mcp
```

Or in `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.soroswap-docs]
url = "https://docs.soroswap.finance/mcp"
```

**VS Code**

Add it to `.vscode/mcp.json`:

```json theme={null}
{
  "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.

**Claude.ai**

1. Open [Settings, Connectors](https://claude.ai/settings/connectors) and choose **Add custom connector**.
2. Name it **Soroswap Docs** and set the URL to `https://docs.soroswap.finance/mcp`.
3. 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.

```bash theme={null}
npx skills add https://docs.soroswap.finance
```

It installs [skill.md](https://docs.soroswap.finance/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.

> [!WARNING]
>
> **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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```markdown theme={null}
## 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](https://docs.soroswap.finance/api/fees.md)) | 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](https://docs.soroswap.finance/api/stellar-gotchas.md) lists each one with the exact error, and
[Errors](https://docs.soroswap.finance/api/errors.md) 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](https://discord.gg/A2rQ3cm9XG).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.