Integrator API

REST API for wallets and payment apps that want swaps on Stellar without running their own routing. Flow: quote → build → your user signs → send. Ufama never sees keys — every transaction is signed client-side by your user's wallet.

Base URL & auth
https://atomicswap-aggregator-production.up.railway.app

Every /v1 request needs an API key, sent as x-api-key or Authorization: Bearer. Keys are issued manually — email hello@ufama.trade. Rate limit: 120 requests/min per key.

POST /v1/quote
{ "assetIn": "XLM", // symbol or SAC contract address "assetOut": "USDC", "amount": "1000000000", // base units (7 decimals), EXACT_IN "slippageBps": 50, // optional, default 50 "feeBps": 25, // optional partner fee, max 100 (1%) "referralAddress": "G..." // required when feeBps > 0 }

Returns amountOut (net of protocol fee and your partner fee), minAmountOut, kind ("classic" or "soroban"), partnerFee, partnerFeeCollected, and the venue segments. Quotes are indicative; build re-prices.

POST /v1/quote/build

Same body plus from (the user address that will sign). Returns an unsigned xdr. Hand it to the user's wallet (Freighter, xBull, LOBSTR — any SEP-43 signer) and have them sign against Public Global Stellar Network ; September 2015.

Partner economics: on classic (SDEX) routes your feeBps is a second payment op inside the same transaction — atomic with the swap, paid in the output asset. Your referralAddress must hold a trustline for every output asset you enable. Soroban routes report partnerFeeCollected: false for now.

POST /v1/send
{ "xdr": "<signed transaction XDR>" }

Submits and returns the result. You can also submit yourself via Horizon (classic) or Soroban RPC (soroban) if you prefer.

GET /v1/tokens · GET /v1/health

/v1/tokens: the tradeable universe with contract addresses and venue-volume ranking (sort by venueVolume for a "top tokens" list). /v1/health: auth check — echoes which partner your key belongs to.

RFQ Maker API

Quote takers directly with firm prices and settle atomically on-chain. You sign one Soroban authorization entry per quote with your own key; Ufama never holds it and never holds funds — there is no escrow. If the taker accepts, their transaction carries your signed entry and both legs settle together or not at all. The protocol fee (0.5 bps) comes out of the taker's payment leg. Issuers can quote their own assets at NAV; the contract can enforce a NAV band on-chain for pairs with an oracle feed.

Flow
GET /api/rfq/stream SSE: request.created / request.closed (x-api-key) GET /api/rfq/open same, for pollers (x-api-key) POST /api/rfq/:id/prepare -> unsigned auth entry for your quote (x-api-key) sign it locally: authorizeEntry(entry, keypair, expiryLedger, passphrase) POST /api/rfq/:id/quote { signedAuthXdr } (x-api-key)

Maker keys are issued manually (same contact as below); the key's label is the trust badge takers see on your quote card. A reference bot that does all of this is in the repo: backend/src/rfq/maker-bot.ts (npm run maker).

POST /api/rfq/:id/prepare
{ "maker": "G...", // the wallet that will sign and deliver "amountOut": "999500000", // base units of tokenOut you deliver for request.amountIn "maxNavDevBps": 50, // optional; 0 = no on-chain NAV check (default 50 when a feed exists) "ttlLedgers": 120 // optional; default = request window + ~1 min grace } → { "quote": { maker, taker, tokenIn, tokenOut, amountIn, amountOut, expiryLedger, nonce, maxNavDevBps }, "authEntryXdr": "<SorobanAuthorizationEntry, unsigned>", "check": { fee, makerReceives, fairOut, vsNavBps } // what the contract will enforce }

The server simulates the full settlement with your balances before answering, so a quote you cannot fund, or one outside its NAV band, is refused here with the contract's own reason. Sign authEntryXdr with validUntilLedgerSeq = quote.expiryLedger.

POST /api/rfq/:id/quote
{ "signedAuthXdr": "<SorobanAuthorizationEntry, signed>" } → { "quote": { id, makerLabel, amountOut, expiryLedger, vsNavBps, status: "live" } }

Every submission is verified against the live host in enforce mode (signature, nonce, expiry, balances, NAV band) before the taker sees it. One live quote per maker per request — a re-quote supersedes. Requests carry a reference (NAV from RedStone/Reflector or the on-chain feed, the best DEX route, standing-book fills) so you can price off the same anchor the taker compares against.

Taker side (public)
POST /api/rfq/request { taker, tokenIn, tokenOut, amountIn, ttlSec? } GET /api/rfq/:id request + live quotes (no signed XDR exposed) POST /api/rfq/:id/accept { quoteId } → { xdr } sign with the taker wallet, submit via /api/swap/submit POST /api/rfq/:id/settled { hash }
Contact

API keys, integration help, or anything else: hello@ufama.trade