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.
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.