Quickstart
Get your API key and make your first request in three steps.
Provision your operator key
Obtain a backend-issued operator key from your deployment administrator. For self-hosting, create an operator and run cargo run -- generate-api-key OPERATOR_UUID integration-label on the backend server. Website signup does not activate payment access.
Your API keys will look like this:
# Prefix examples only; operator configuration selects the network
sk_test_a1b2c3d4e5f6g7h8i9j0...
# Verify Horizon, issuer, and network passphrase before sending funds
sk_live_a1b2c3d4e5f6g7h8i9j0...
Keep your secret keys safe. Never expose them in client-side code, public repos, or browser requests. Always call the Stackr API from your backend.
Make your first API call
Check service health first (this endpoint is public), then verify your operator key by checking a registered account’s balance:
# Verify your connection
curl https://api.usestackr.xyz/health
# {"status":"healthy","database":true,"redis":true,"stellar":true}# Check a wallet balance
curl https://api.usestackr.xyz/api/v1/accounts/+250781234567/balance \ -H "Authorization: Bearer sk_test_your_key_here"
# Send USDC
# Run from the Stackr repository; set STACKR_API_KEY, STACKR_USER_PIN, and STACKR_PAYMENT_ID securely.
# Reuse STACKR_PAYMENT_ID on retries; regenerate the encrypted PIN envelope.
# Generate the encrypted body and pipe it to curl without a plaintext PIN field.
node --input-type=module <<'JS' | curl -X POST https://api.usestackr.xyz/api/v1/transfers \
-H "Authorization: Bearer $STACKR_API_KEY" \
-H "Idempotency-Key: $STACKR_PAYMENT_ID" \
-H "Content-Type: application/json" --data-binary @-
import { encryptPin } from './scripts/encrypt-pin.mjs';
const body = {
"sender_phone": "+250781234567",
"recipient_phone": "+250789876543",
"amount": 10
};
body.pin = encryptPin(process.env.STACKR_USER_PIN, process.env.STACKR_API_KEY, '/api/v1/transfers');
process.stdout.write(JSON.stringify(body));
JSIntegrate into your app
Call the Stackr API from your backend. Here are examples in common languages:
Node.js / JavaScript
// Backend only. Import scripts/encrypt-pin.mjs from Stackr.
import { encryptPin } from './scripts/encrypt-pin.mjs';
const apiKey = process.env.STACKR_API_KEY;
const path = '/api/v1/transfers';
const paymentId = crypto.randomUUID(); // Create once per intended payment.
// Generate a fresh { version, timestamp, nonce, ciphertext } object.
const pin = encryptPin(process.env.STACKR_USER_PIN, apiKey, path);
const response = await fetch('https://api.usestackr.xyz' + path, {
method: 'POST',
headers: {
Authorization: 'Bearer ' + apiKey,
'Content-Type': 'application/json',
'Idempotency-Key': paymentId, // Persist this ID and reuse it on retries.
},
body: JSON.stringify({
sender_phone: '+250781234567',
recipient_phone: '+250789876543',
amount: 10.00,
pin, // Encrypted object; the raw PIN is never sent in this body.
}),
});
const result = await response.json();
// Example successful response
// { "tx_hash": "3d8f4a2b1c9e...", "status": "confirmed" }Python
# Backend only: pip install cryptography requests
import requests
import os
import time
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
api_key = os.environ["STACKR_API_KEY"]
path = "/api/v1/transfers"
timestamp = int(time.time())
nonce = os.urandom(12)
key = HKDF(algorithm=hashes.SHA256(), length=32,
salt=b"stackr-api-pin-v1", info=b"aes-256-gcm").derive(api_key.encode())
aad = f"stackr-api-pin-v1\nPOST\n{path}\n{timestamp}".encode()
ciphertext = AESGCM(key).encrypt(nonce, os.environ["STACKR_USER_PIN"].encode(), aad)
pin = {"version": 1, "timestamp": timestamp,
"nonce": base64.b64encode(nonce).decode(),
"ciphertext": base64.b64encode(ciphertext).decode()}
response = requests.post(
"https://api.usestackr.xyz/api/v1/transfers",
headers={"Authorization": f"Bearer {os.environ['STACKR_API_KEY']}",
"Idempotency-Key": os.environ["STACKR_PAYMENT_ID"]},
json={
"sender_phone": "+250781234567",
"recipient_phone": "+250789876543",
"amount": 10.00,
"pin": pin,
},
)
result = response.json()
print(result["tx_hash"]) # "3d8f4a2b..."
Next steps
- •Browse the API Reference for all endpoints with request/response examples
- •Read the Developer Guide to understand the USSD protocol, wallet system, and Stellar integration
- •Review Security best practices for handling API keys and user data
- •Check out Pricing to see which plan fits your usage