curl --request POST \
  --url https://api.soroswap.finance/swap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assetIn": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
  "assetOut": "CDTKPWPLOURQA2SGTKTUQOWRCBZEORB4BWBOMJ3D3ZTQQSGE5F6JBQLV",
  "amount": "10000000",
  "tradeType": "EXACT_IN",
  "protocols": [
    "soroswap",
    "aqua",
    "sdex"
  ],
  "slippageBps": "50",
  "from": "GBQJ4HBCQHJQKSKNT3JRKC5VKA3QJUXBVFWIVSMHKPQSJ7XP2IXTCAAK"
}
'

{
  "quote": {},
  "xdr": "AAAAAgAAAAB8shYDi1JO9x2/3jMeVzK2IGtrsFVWLCL4uHRJf+YPyAAAA+gCzi7H...",
  "action": "SIGN_TRANSACTION",
  "message": "Sign the transaction with the user wallet and send the signed XDR to /send endpoint or your own rpc",
  "actionData": {},
  "simulated": false,
  "prerequisites": [
    {
      "action": "CREATE_TRUSTLINE",
      "xdr": "AAAAAgAAAABiSu3MsKtQvDuQO5i2b...",
      "signer": "GBQJ4HBCQHJQKSKNT3JRKC5VKA3QJUXBVFWIVSMHKPQSJ7XP2IXTCAAK",
      "assetCode": "USDC",
      "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "description": "<string>"
    }
  ]
}

Swap

Swap (all-in-one)

Quotes, builds and simulates a swap in a single call: the equivalent of calling /quote and then /quote/build.

Send the same parameters as /quote plus the wallet address (from, a G account or C contract). The response always includes the quote, plus an action field telling you what to do next:

SIGN_TRANSACTION — xdr is the simulated swap transaction, ready to be signed and sent to /send or your own rpc.
CREATE_TRUSTLINE — the account is missing a trustline for the output asset. xdr is a changeTrust transaction: sign it, submit it, then call this endpoint again to get the swap XDR. Details (signer, assetCode, assetIssuer) come in actionData.
Other actions (e.g. RESTORE_BALANCE) follow the same pattern: xdr is the transaction that resolves the action.

📦 Inline prerequisites

Pass inlinePrerequisites: true to always receive the swap XDR in a single call, even when a trustline is missing. Instead of a CREATE_TRUSTLINE action, the trustline transaction comes in a prerequisites array: sign and submit each prerequisite in order, then handle the swap XDR according to simulated:

simulated: true (SDEX routes) — the swap XDR is complete; sign it and send it.
simulated: false (Soroban routes) — simulation cannot succeed until the trustline exists, so the swap XDR has no footprint, resource fees or auth entries. Re-simulate and assemble it (footprint, resources and auth entries are regenerated automatically), or override sequence and Soroban resources yourself, before signing and sending. Submitting it as-is will fail.

The swap XDR’s sequence number already accounts for the prerequisite transactions when they share the same source account. Only the missing-trustline case becomes a prerequisite; other actions (e.g. RESTORE_BALANCE) keep the action flow described above.

⚡ Gasless Trustline

Pass gaslessTrustline: "create" together with a sponsor address to get a single SDEX transaction that opens the trustline and swaps. The returned XDR must be signed by both the user and the sponsor.

Note: The two-step Soroban sponsored flow (user signature + fee bump) is not supported here — use /quote and /quote/build for that.

💰 Fees

feeBps and referralId are accepted for compatibility and ignored: the fee comes from your authenticated principal’s partner rate, and fee destinations are no longer caller-supplied. The values you send are recorded so Soroswap can seed your profile and propose your payout address. The quote includes platformFee only when a partner rate applies.

POST

swap

curl --request POST \
  --url https://api.soroswap.finance/swap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assetIn": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
  "assetOut": "CDTKPWPLOURQA2SGTKTUQOWRCBZEORB4BWBOMJ3D3ZTQQSGE5F6JBQLV",
  "amount": "10000000",
  "tradeType": "EXACT_IN",
  "protocols": [
    "soroswap",
    "aqua",
    "sdex"
  ],
  "slippageBps": "50",
  "from": "GBQJ4HBCQHJQKSKNT3JRKC5VKA3QJUXBVFWIVSMHKPQSJ7XP2IXTCAAK"
}
'

{
  "quote": {},
  "xdr": "AAAAAgAAAAB8shYDi1JO9x2/3jMeVzK2IGtrsFVWLCL4uHRJf+YPyAAAA+gCzi7H...",
  "action": "SIGN_TRANSACTION",
  "message": "Sign the transaction with the user wallet and send the signed XDR to /send endpoint or your own rpc",
  "actionData": {},
  "simulated": false,
  "prerequisites": [
    {
      "action": "CREATE_TRUSTLINE",
      "xdr": "AAAAAgAAAABiSu3MsKtQvDuQO5i2b...",
      "signer": "GBQJ4HBCQHJQKSKNT3JRKC5VKA3QJUXBVFWIVSMHKPQSJ7XP2IXTCAAK",
      "assetCode": "USDC",
      "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "description": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

network

enum<string>

Network on which the operation will be performed

Available options:

testnet,

mainnet

Body

application/json

Data required to quote and build the swap

assetIn

string

required

Input asset contract address

Example:

"CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA"

assetOut

string

required

Output asset contract address

Example:

"CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75"

amount

integer<int64>

required

Expected input amount in stroops

Example:

"10000000"

tradeType

enum<string>

required

Type of trade: EXACT_IN = input fixed; EXACT_OUT = output fixed

Available options:

EXACT_IN,

EXACT_OUT

Example:

"EXACT_IN"

protocols

array[]

required

Array of protocols to aggregate liquidity from

Example:

["soroswap", "aqua"]

from

string

required

The wallet address (G account or C contract) that will send the funds and sign the transaction

Example:

"GBQJ4HBCQHJQKSKNT3JRKC5VKA3QJUXBVFWIVSMHKPQSJ7XP2IXTCAAK"

parts

number

Number of route splits for optimization. Higher values improve price discovery but increase latency. Max: 1000..

Example:

10

slippageBps

number

Slippage tolerance in basis points (bps). 10000 = 100%, 100 = 1%, 50 = 0.5%. Default is 50 bps (0.5%)

Example:

"50"

maxHops

number

Maximum number of hops to aggregate liquidity from

Example:

2

assetList

string[]

Restricts intermediate tokens to a specific list. Only useful for Soroban transactions (Router and Aggregator). Not useful for SDEX.

Example:

[
  "SOROSWAP",
  "STELLAR_EXPERT",
  "AQUA",
  "LOBSTR"
]

feeBps

number

Ignored. Your fee rate lives in your partner profile (see GET /partner). Kept for wire compatibility; the value you send is recorded so Soroswap can seed your profile.

Example:

50

gaslessTrustline

string

Whether to use gasless trustline swap. Only use this if you are sure that the user does not have a trustline for the output asset and if you have an sponsor account.

Example:

true

string

The wallet address that will receive the funds. Defaults to the from address. Must equal from when gaslessTrustline is enabled

referralId

string

Ignored. Fee destinations are no longer caller-supplied; the value you send is recorded so Soroswap can propose your payout address.

The wallet address that will sponsor the trustline. Only supported for the Gasless Trustline (SDEX) flow

inlinePrerequisites

boolean

When true and a trustline is missing, the response still contains the swap XDR: the trustline transaction is returned in a prerequisites array instead of replacing the swap. Prerequisites must be signed and submitted in order first. For Soroban routes the swap XDR is returned unsimulated (simulated: false) since simulation cannot succeed until the trustline exists — re-simulate it (or override sequence and Soroban resources) before submitting

Example:

true

Response

Quote and transaction (or required action) returned successfully

quote

object

The quote for the swap, same schema as the /quote response

xdr

string

Unsigned transaction XDR: the swap when action is SIGN_TRANSACTION, or the transaction that resolves the required action (e.g. a changeTrust for CREATE_TRUSTLINE)

Example:

"AAAAAgAAAAB8shYDi1JO9x2/3jMeVzK2IGtrsFVWLCL4uHRJf+YPyAAAA+gCzi7H..."

action

enum<string>

What to do next with the returned XDR

Available options:

SIGN_TRANSACTION,

CREATE_TRUSTLINE,

RESTORE_BALANCE,

RESTORE_CONTRACT

Example:

"SIGN_TRANSACTION"

message

string

Human-readable explanation of the required action

Example:

"Sign the transaction with the user wallet and send the signed XDR to /send endpoint or your own rpc"

actionData

object

Extra details when action is not SIGN_TRANSACTION (e.g. signer, assetCode, assetIssuer for CREATE_TRUSTLINE)

simulated

boolean

Only present in inline-prerequisites mode. false means the swap XDR was built without simulation (no footprint, resource fees or auth entries) and must be re-simulated and assembled before submission

Example:

false

prerequisites

object[]

Only present in inline-prerequisites mode: transactions to sign and submit, in order, before the swap XDR

Show child attributes

Swap

Partner

Market data

Account

Utilities

Swap (all-in-one)

📦 Inline prerequisites

⚡ Gasless Trustline

💰 Fees

Authorizations

Query Parameters

Body

Response