API Reference
19 endpoints with curl examples, request/response payloads, and error codes.
Base URL
https://api.usestackr.xyz
Testnet: https://testnet.api.usestackr.xyz
Authentication
Payment POSTs require an Idempotency-Key. Reuse that key and payment details on retries, with a fresh encrypted PIN envelope. HTTP 202 means settlement is pending; HTTP 409 means a conflicting request or an unresolved payment. Quote-based swaps use their quote ID.
API v1 endpoints require your secret API key in the Authorization header. Obtain a backend-issued operator key from your deployment administrator. Website signup does not provision API access.
Authorization: Bearer sk_live_your_api_key_here
Test key (testnet)
sk_test_... (illustrative)
Prefix example only; verify the operator’s configured network.
Live key (mainnet)
sk_live_... (illustrative)
Production. Real USDC on Stellar mainnet.
Never expose your secret key in client-side code. Always make Stackr API calls from your backend server.
Encrypted PIN requests
Your project’s API key authenticates its operator account. Your end user’s PIN authorizes their wallet operation. Encrypt the PIN on your backend; users do not need your API key. Normal telco USSD callbacks use the existing USSD protocol.
Every PIN-bearing endpoint accepts an AES-256-GCM encrypted object in the pin field. Envelopes expire after five minutes and can only be used once. Generate them on your backend with a fresh random nonce for each request.
Examples below generate encrypted PIN objects on your backend. Legacy PIN strings remain supported for existing clients. Operators can set REQUIRE_ENCRYPTED_API_PINS=true to require encryption. HTTPS is required in either mode.
Rate Limiting
The table below shows proposed hosted plan limits, not enforced Rust API quotas. USSD callbacks are rate-limited by source IP; PIN attempts are limited per operator and phone.
Free
60 req/min
1,000/month
Pro
300 req/min
50,000/month
Enterprise
Custom
Unlimited
When rate-limited, the server returns 429 Too Many Requests.
Core EndpointsNo authentication required
API v1AUTH REQUIRED
Error Format
All errors follow a consistent JSON structure:
{
"error": "Daily transaction limit exceeded"
}