Balance swaps

A balance swap converts part of your store balance from one asset into another without leaving SouthPay. Use it to consolidate deposits into a single stablecoin before a payout, or to move off a chain whose network fees you no longer want to pay. Swaps are executed by an external routing provider, so the amount you receive is not known in advance. Quote first, then create. Paths are relative to https://api.southpay.io/api/v2.

Authentication

Any valid API key or OAuth token can call these endpoints. Balance swaps are not scope-checked, so no specific scope is required. Publishable keys are still rejected.

Creating a swap runs a step-up MFA check. That check is a no-op for API keys and OAuth tokens; it only gates dashboard sessions, which return 403 mfa_required without two-factor enabled.

Quote a swap

POST /balance_swaps/quote. No idempotency key, creates nothing.

string

required

The asset to sell, for example ETH_USDC.

string

required

The asset to receive. Must differ from source_asset_id.

string

required

Amount to sell, in atomic units of source_asset_id. Must be positive.

curl -X POST https://api.southpay.io/api/v2/balance_swaps/quote \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "source_asset_id": "ETH_USDC",
    "buy_asset_id": "ETH_USDT",
    "sell_amount_atomic": "250000000"
  }'

{
  "source_asset_id": "ETH_USDC",
  "buy_asset_id": "ETH_USDT",
  "sell_amount_atomic": "250000000",
  "estimated_buy_amount_atomic": "249400000",
  "min_received_atomic": "248652800",
  "slippage_bps": 30,
  "buy_atomic_decimals": 6
}

string

required

What the route currently expects to return, in atomic units of buy_asset_id.

string

required

The floor after slippage: estimated * (10000 - slippage_bps) / 10000. Size your downstream payout against this, not against the estimate.

integer

required

Slippage tolerance in basis points.

integer

required

Divisor exponent for the two atomic amounts above.

A quote carries no expiry field and reserves nothing. Treat it as indicative and re-quote if more than a few seconds pass.

Create a swap

POST /balance_swaps. Idempotency-Key is required. Same three parameters as the quote, sent at the top level.

string

required

The asset to sell.

string

required

The asset to receive.

string

required

Atomic units of source_asset_id. Must be positive and available in your balance.

curl -X POST https://api.southpay.io/api/v2/balance_swaps \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: swap_2026_05_12_a" \
  -d '{
    "source_asset_id": "ETH_USDC",
    "buy_asset_id": "ETH_USDT",
    "sell_amount_atomic": "250000000"
  }'

{
  "id": "6f5e4d3c-2b1a-4098-8f7e-6d5c4b3a2918",
  "status": "pending",
  "source_asset_id": "ETH_USDC",
  "buy_asset_id": "ETH_USDT",
  "sell_amount_atomic": "250000000",
  "expected_buy_amount_atomic": "249400000",
  "actual_buy_amount_atomic": null,
  "swap_provider": "swapkit",
  "tx_hash": null,
  "livemode": true,
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z"
}

Swaps are irreversible and execute at the market rate at the time of fill, which can differ from the quote. Replaying the same Idempotency-Key returns the original swap, still with status 201, not 200. A new key executes a second swap.

Response fields

string

required

Bare UUID.

string

required

pending, submitted, completed or failed.

string

required

Amount debited from source_asset_id.

string | null

Estimate recorded at creation.

string | null

What actually arrived. Null until the swap completes. This is the number to reconcile against.

string | null

Routing provider that executed the swap.

string | null

On-chain hash, once broadcast.

boolean

required

Retrieve a swap

GET /balance_swaps/{id}. Returns a bare swap object. Unknown id returns 404 {"error": "Balance swap not found"}. There are no swap webhooks. Poll this endpoint until status is completed or failed.

List swaps

GET /balance_swaps. Newest first.

string

pending, submitted, completed or failed.

integer

default:"1"

integer

default:"25"

Between 1 and 100.

Response 200

{
  "data": [ { "id": "6f5e4d3c-2b1a-4098-8f7e-6d5c4b3a2918", "status": "completed", "…": "…" } ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Balance swaps use the pagination envelope, matching payouts. Payments and billing use meta instead.

Lifecycle

Status	Terminal	Meaning
`pending`	No	Created, source funds reserved.
`submitted`	No	Sent to the routing provider.
`completed`	Yes	Filled. `actual_buy_amount_atomic` is set and the target balance has increased.
`failed`	Yes	Not filled. The source reservation is released.

Auto-swap is the automatic version of this, applied to incoming payments rather than to your standing balance. It is configured in the dashboard, not over the API, and its outcome surfaces as auto_swap_status and auto_swap_detail on a payment intent. Auto-swap targets are limited to ETH_USDC and ETH_USDT; manual swaps are not.

Errors

Status	Body	Cause
`422`	`{"error": "Idempotency-Key header is required"}`	Header missing on create.
`404`	`{"error": "Source asset not found"}`	Unknown or inactive `source_asset_id`.
`404`	`{"error": "Target asset not found"}`	Unknown or inactive `buy_asset_id`.
`422`	`{"error": "sell_amount_atomic must be positive"}`	Zero, negative or missing.
`422`	`{"error": "Source and target assets must be different"}`	Both ids are the same.
`422`	`{"error": "USDC cannot be swapped"}`	The source asset has no swap route configured.
`422`	`{"error": "USDT cannot be received from a swap"}`	The target asset cannot be a swap output.
`422`	`{"error": "Insufficient USDC balance for swap"}`	Balance is short.
`422`	`{"error": "No swap route available for this pair", "code": "no_route"}`	Quote only. No route exists between the two assets.
`503`	`{"error": "Could not fetch a swap quote, please try again", "code": "quote_unavailable"}`	Quote only. The routing provider is unreachable. Retry with backoff.

Only the last two carry a code. The rest use the flat {"error": "<message>"} envelope with no machine-readable identifier, so branch on the status code and the endpoint rather than on the message text.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Authentication

Quote a swap

Create a swap

Response fields

Retrieve a swap

List swaps

Lifecycle

Errors

​Authentication

​Quote a swap

​Create a swap

​Response fields

​Retrieve a swap

​List swaps

​Lifecycle

​Related: auto-swap

​Errors

Authentication

Quote a swap

Create a swap

Response fields

Retrieve a swap

List swaps

Lifecycle

Related: auto-swap

Errors