Soroswap integration

Quote a USDC ↔ XLM swap, let the user confirm the minimum output, then track settlement on Stellar.

1. Request a quote

Call this from your backend using your Stackr API key. Amounts are decimal strings with up to seven decimal places. Slippage defaults to 50 bps (0.5%) and is capped at 100 bps (1%).

POST /api/v1/swaps/quote
Authorization: Bearer YOUR_STACKR_API_KEY
Content-Type: application/json

{
  "phone": "+250781234567",
  "source_asset": "USDC",
  "dest_asset": "XLM",
  "amount": "10.0000000",
  "slippage_bps": 50
}

Display amount, expected_amount, minimum_received, maximum_network_fee in XLM, and expires_at before the user confirms. Quotes expire after 120 seconds by default.

2. Confirm with an encrypted PIN

Use the quote ID returned by Stackr. Generate the PIN envelope on your backend using the repository’s encryption helper. Never expose either API key in browser code.

// Backend only: scripts/encrypt-pin.mjs from the Stackr repository
import { encryptPin } from './encrypt-pin.mjs';

const path = '/api/v1/swaps';
const pin = encryptPin(userPin, process.env.STACKR_API_KEY, path);
const response = await fetch('https://api.usestackr.xyz' + path, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.STACKR_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ phone, quote_id: quote.quote_id, pin })
});
const swap = await response.json();

The server builds from its saved quote and validates the wallet, exact input, asset pair, minimum output, fee ceiling and approved contracts before signing. Do not send amount or asset fields with quote_id.

PIN encryption format →

3. Check settlement

GET /api/v1/swaps/QUOTE_ID?phone=%2B250781234567
Authorization: Bearer YOUR_STACKR_API_KEY

Pending or building confirmation returns HTTP 202. Terminal states return HTTP 200; always inspect status. Repeating confirmation for the same quote returns its existing state. Only one Soroswap trade can be building or pending per wallet. An uncertain submission remains pending and is reconciled by its transaction hash.

received_amount is actual ledger output when available, otherwise null. expected_amount is the original estimate. A confirmed swap may have null output if the provider’s metadata format cannot be decoded; verify the account balance. Do not start another trade to resolve a timeout.

USSD and operator setup

The USSD flow uses the same stored quotes: choose a pair, enter an amount, review the expected and minimum output plus fee ceiling, then confirm with a PIN. Enter 0 to cancel. An expired quote requires a fresh preview.

# Backend environment: example, not actual credentials
SWAP_PROVIDER=soroswap
SOROSWAP_API_KEY=YOUR_PROVIDER_KEY
SOROSWAP_TESTNET_ROUTER_CONTRACT=VERIFIED_ROUTER_ADDRESS
SOROSWAP_TESTNET_AGGREGATOR_CONTRACT=VERIFIED_AGGREGATOR_ADDRESS
SOROSWAP_QUOTE_TTL_SECS=120
SOROSWAP_MAX_FEE_STROOPS=10000000

The operator’s issuer, network passphrase and Horizon endpoint must match the selected network. User wallets pay network fees. Swaps reserve their USDC-equivalent daily spend before signing; failed settlement releases the reservation. Startup applies the swap quote and payment safety migrations. Test both directions, duplicate confirmation, expiry and timeout recovery before launch.

Request and response reference →