Quickstart

Get your API key and make your first request in three steps.

1

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.

2

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));
JS
3

Integrate 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