> ## 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://console.soroswap.finance/register. A missing or invalid key returns 401 with code and registerUrl (POST /send returns 403 instead); an expired JWT or a missing role returns 403. 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.
> Partner id: every account has one (9 hex chars, permanent). Read partnerId from GET /partner, or in the console at https://console.soroswap.finance under Fees & payouts. The partner fee itself is switched on by Soroswap; see https://docs.soroswap.finance/api/fees.md.
> 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.

# Quickstart

> Mainnet in four calls: POST /quote (C... asset addresses, amount as an integer string in stroops), POST /quote/build with the unchanged quote and from, sign, POST /send. Also the API key, testnet, and API-built versus contract execution.

## First, choose how you execute

The API always returns the best route. How that route reaches the chain is your choice, and it
decides which guide you follow.

| | **The API builds the transaction** | **You execute from your own contract** |
| - | - | - |
| Who it is for | Wallets, apps and backends that sign for a user or a `G...` account | Protocols and routers that already call contracts on-chain, and smart wallets (`C...` accounts) |
| What you call | `/quote`, then `/quote/build`, then `/send` (or submit yourself) | `/quote`, then pass `rawTrade.distribution` to the aggregator contract's `swap_exact_in` / `swap_exact_out` |
| Venues | All of them, SDEX included | Soroban venues only: leave `sdex` out of `protocols`, or execute SDEX quotes separately ([Routing through SDEX](https://docs.soroswap.finance/api/sdex.md)) |
| Fees | Applied by the API from your account | Pass your partner in the contract call ([Fees and revenue share](https://docs.soroswap.finance/api/fees.md)) |
| Guide | This page | [Execute from your own contract](https://docs.soroswap.finance/aggregator/technical-reference/cross-contract-integration.md) |

The rest of this page follows the first path.

## 1. Get an API key

1. [Sign up in the console](https://console.soroswap.finance/register), or
   [sign in](https://console.soroswap.finance/login) if you have an account.
2. Open **API keys** and click **Generate**. The key starts with `sk_` and is shown once, so copy
   it then. Generating again replaces it.
3. Send it on every request as `Authorization: Bearer sk_...`.

A missing, invalid or revoked key returns **401** with a `code` and a `registerUrl`, except on
`POST /send`, which returns **403**; see [Errors](https://docs.soroswap.finance/api/errors.md#authentication). Keep the key on your
server: a key in frontend code is a key anyone can use against your rate limit.

The [Console](https://docs.soroswap.finance/api/console.md) page lists what else you can manage there.

## 2. Quote

```bash theme={null}
curl -X POST "https://api.soroswap.finance/quote?network=mainnet" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "assetIn": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    "assetOut": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
    "amount": "100000000",
    "tradeType": "EXACT_IN",
    "protocols": ["soroswap", "aqua", "sushi", "comet", "sdex"],
    "slippageBps": 50
  }'
```

* `assetIn` and `assetOut` are contract addresses (`C...`). The two above are XLM and USDC on mainnet.
* `amount` is in stroops, the asset's smallest unit (7 decimals for XLM and USDC).
* `protocols` lists the venues to consider. `GET /protocols?network=mainnet` returns the accepted
  values. SDEX is only priced when `sdex` is in the list.
* `slippageBps` is optional and defaults to 50 (0.5%).

The response carries `amountIn`, `amountOut`, the minimum you will accept
(`otherAmountThreshold`), the `routePlan` and a `platform` field that says how the route
executes: `aggregator`, `router` or `sdex`.

## 3. Build, sign and send

```javascript theme={null}
const API = 'https://api.soroswap.finance'
const headers = {
  Authorization: `Bearer ${process.env.SOROSWAP_API_KEY}`,
  'Content-Type': 'application/json',
}

async function post(path, body) {
  const res = await fetch(`${API}${path}?network=mainnet`, {
    method: 'POST',
    headers,
    body: JSON.stringify(body),
  })
  if (!res.ok) throw new Error(`${path} ${res.status}: ${await res.text()}`)
  return res.json()
}

const quote = await post('/quote', {
  assetIn: 'CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA', // XLM
  assetOut: 'CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75', // USDC
  amount: '100000000', // 10 XLM
  tradeType: 'EXACT_IN',
  protocols: ['soroswap', 'aqua', 'sushi', 'comet', 'sdex'],
})

// Send the quote back unchanged. `from` signs; `to` receives (defaults to `from`).
const { xdr } = await post('/quote/build', { quote, from: userAddress, to: userAddress })

const signedXdr = await signWithWallet(xdr) // Freighter, Stellar Wallets Kit, your own signer

const result = await post('/send', { xdr: signedXdr })
console.log(result.txHash, result.success)
```

You can also submit the signed transaction through your own Soroban RPC or Horizon instead of
`/send`.

Build soon after you quote. Prices move, and if your partner fee changed in between,
`/quote/build` returns **409**: quote again and build from the new quote.

## Testnet

Use the same base URL with `?network=testnet`. Testnet quotes come only from Soroswap pools and
carry no fee. Fund an account with Friendbot and mint test tokens at
[faucet.soroswap.finance](https://faucet.soroswap.finance).

## Next

* [Fees and revenue share](https://docs.soroswap.finance/api/fees.md): earn on the swaps you route.
* [Gasless Trustline](https://docs.soroswap.finance/api/gasless-trustline.md): onboard users who hold no XLM.
* [Errors](https://docs.soroswap.finance/api/errors.md) and [Going to production](https://docs.soroswap.finance/api/going-to-production.md).
* [API Reference](https://docs.soroswap.finance/api-reference/quote/quote.md): every endpoint and field.
* [Beginner guide](https://docs.soroswap.finance/api/beginner-guide.md): the same flow step by step, with a Freighter example.


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