Swap between crypto coins and networks in your balance

Use the swap endpoints to exchange one cryptocurrency or network balance for another directly within your PeerPesa wallet. For example, you can swap USDC on Stellar for cUSD on Celo, or XLM for USDC on the same network. Swaps use a two-step flow: first request a locked quote that fixes the rate and fees for exactly 30 minutes, then execute the quote. If the market moves beyond your configured slippage tolerance before execution, the swap fails with a slippage_exceeded error.

Sandbox
Production

Base URL: https://sandbox-api.peerpesa.co/v1

Base URL: https://api.peerpesa.co/v1

All requests require an Authorization: Bearer <token> header. POST endpoints accept an optional Idempotency-Key header to prevent duplicate transactions. Amounts are decimal strings. Network codes are uppercase as returned by GET /currencies: STELLAR, CELO, BITCOIN.

Generate a swap quote

Request a quote for swapping one asset to another. The quote locks the rate, minimum received amount, and fees for 30 minutes.

Endpoint

POST /wallet/swap/quote

Request headers

string

required

Bearer token

string

Optional unique key to prevent duplicate quote creation

Request body

object

required

Asset you are swapping from

Show properties

string

required

Source token, e.g. USDC, XLM, BTC

string

required

Source network, e.g. STELLAR, CELO, BITCOIN

object

required

Asset you are swapping to

Show properties

string

required

Target token, e.g. CUSD, USDC, USDT

string

required

Target network, e.g. STELLAR, CELO, BITCOIN

string

required

Amount to swap as a decimal string

string

required

Which side the amount refers to: from or to

number

Maximum acceptable slippage as a percentage, e.g. 0.5 for 0.5%. Defaults to the slippage value from GET /currencies or 0.5% if not specified.

Response fields

string

Quote ID, e.g. sq_...

object

Show properties

string

Source token

string

Source network

string

Amount deducted from balance

object

Show properties

string

Target token

string

Target network

string

Amount you will receive

string

Exchange rate (to per from unit)

string

Minimum amount you are guaranteed to receive, based on slippage

object

Fee breakdown:

Show properties

string

Total fee in source asset

string

Source asset symbol

string

Platform fee

string

Network fee

number

Slippage percentage used for this quote

string

ISO 8601 timestamp. Quote expires 30 minutes after created_at.

string

ISO 8601 timestamp

Example request

curl -X POST https://api.peerpesa.co/v1/wallet/swap/quote \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "symbol": "USDC",
      "network": "STELLAR"
    },
    "to": {
      "symbol": "CUSD",
      "network": "CELO"
    },
    "amount": "100.00",
    "amount_side": "from",
    "slippage": 0.5
  }'

const res = await fetch("https://api.peerpesa.co/v1/wallet/swap/quote", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: { symbol: "USDC", network: "STELLAR" },
    to: { symbol: "CUSD", network: "CELO" },
    amount: "100.00",
    amount_side: "from",
    slippage: 0.5,
  }),
});
const data = await res.json();
console.log(data);

Example response

{
  "id": "sq_7xYz9AbCdEfGhIjK",
  "from": {
    "symbol": "USDC",
    "network": "STELLAR",
    "amount": "100.00"
  },
  "to": {
    "symbol": "CUSD",
    "network": "CELO",
    "amount": "99.45"
  },
  "rate": "0.9945",
  "minimum_received": "98.95",
  "fee": {
    "total": "0.55",
    "currency": "USDC",
    "app_fee": "0.30",
    "network_fee": "0.25"
  },
  "slippage": 0.5,
  "expires_at": "2024-01-15T14:30:00Z",
  "created_at": "2024-01-15T14:00:00Z"
}

Execute a swap

Execute a previously generated swap quote to create a swap transaction. The swap deducts the source asset from your balance and credits the target asset.

Endpoint

POST /wallet/swap

Request headers

string

required

Bearer token

string

Optional unique key to prevent duplicate execution

Request body

string

required

ID of the swap quote to execute, e.g. sq_7xYz9AbCdEfGhIjK

string

Optional external reference string

Response fields

The response is a wallet transaction object.

string

Transaction ID, e.g. txn_...

string

Always swap

string

pending, processing, completed, failed, or refunded

object

Source asset details:

Show properties

string

Source token

string

Source network

string

Amount debited

object

Target asset details:

Show properties

string

Target token

string

Target network

string

Amount credited

object

Fee breakdown as in the quote

string

Net target amount received after fees

string

External reference if provided

string

On-chain transaction hash (null until completed)

string

ISO 8601 timestamp

string

ISO 8601 timestamp

Example request

curl -X POST https://api.peerpesa.co/v1/wallet/swap \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "sq_7xYz9AbCdEfGhIjK",
    "reference": "swap_2024_001"
  }'

const res = await fetch("https://api.peerpesa.co/v1/wallet/swap", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    quote_id: "sq_7xYz9AbCdEfGhIjK",
    reference: "swap_2024_001",
  }),
});
const data = await res.json();
console.log(data);

Example response

{
  "id": "txn_mNo4PqRs5TuV6wX7",
  "type": "swap",
  "status": "pending",
  "from": {
    "symbol": "USDC",
    "network": "STELLAR",
    "amount": "100.00"
  },
  "to": {
    "symbol": "CUSD",
    "network": "CELO",
    "amount": "99.45"
  },
  "fee": {
    "total": "0.55",
    "currency": "USDC",
    "app_fee": "0.30",
    "network_fee": "0.25"
  },
  "net_amount": "99.45",
  "reference": "swap_2024_001",
  "tx_hash": null,
  "created_at": "2024-01-15T14:05:00Z",
  "updated_at": "2024-01-15T14:05:00Z"
}

Understanding slippage

Slippage is the difference between the quoted price and the actual execution price. Market prices can change between quote generation and execution, especially for cross-network swaps. When you request a quote, you set a slippage tolerance as a percentage. If the executable rate moves unfavorably beyond that tolerance before you execute, the API returns a slippage_exceeded error and you must request a fresh quote.

A lower slippage gives you better price protection but increases the chance the quote becomes unexecutable. A higher slippage makes execution more likely but you may receive less than quoted.

The minimum_received field in the quote shows the worst-case amount you are guaranteed to receive if the swap executes within tolerance.

Error codes

Code	Status	Meaning
`unsupported_network`	422	One of the networks is not active or available for swapping
`unsupported_asset`	422	One of the symbol/network combinations is not supported
`amount_too_low`	422	The amount is below the minimum for the source or target asset
`amount_too_high`	422	The amount exceeds the maximum for the source or target asset
`insufficient_balance`	422	Your wallet balance is too low to cover the swap amount plus fees
`quote_expired`	422	The quote expired after 30 minutes. Request a new quote
`slippage_exceeded`	422	Market moved beyond your slippage tolerance. Request a new quote
`network_unavailable`	503	One of the networks is temporarily unavailable

Step-by-step flow

Request a quote

Call POST /wallet/swap/quote with your from/to assets, amount, and optional slippage tolerance.

Review the quote

Check the rate, minimum_received, and fee. The quote is valid for 30 minutes.

Execute the quote

Call POST /wallet/swap with the quote_id. No additional balance checks are needed.

Track completion

Poll GET /orders/{order_id} or listen for webhook events transaction.processing, transaction.completed, and transaction.failed.

​Generate a swap quote

​Endpoint

​Request headers

​Request body

​Response fields

​Example request

​Example response

​Execute a swap

​Endpoint

​Request headers

​Request body

​Response fields

​Example request

​Example response

​Understanding slippage

​Error codes

​Step-by-step flow

Generate a swap quote

Endpoint

Request headers

Request body

Response fields

Example request

Example response

Execute a swap

Endpoint

Request headers

Request body

Response fields

Example request

Example response

Understanding slippage

Error codes

Step-by-step flow