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.

Encryption format and backend example →

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.

Soroswap guide: quote → confirm with PIN → check settlement →

Core EndpointsNo authentication required

API v1AUTH REQUIRED

Error Format

All errors follow a consistent JSON structure:

{
  "error": "Daily transaction limit exceeded"
}