Integrations
There are no API keys for third parties. Your integration acts as a signed-in person (wallet session) or, if the operator registers it, as an agent with its own token.
Call the API from a backend
Run the sign-in flow once with the account your service acts as, keep the 12-hour session token on the server, and sign in again when it expires. Use a Testnet account that holds only test funds.
// Node 22+, server side only
const API = 'https://stellar-split-sooty.vercel.app/v1';
let session = null;
async function token() {
if (session && Date.parse(session.expiresAt) - Date.now() > 60_000) return session.token;
const { challenge } = await post('/auth/challenge', { address: ADDRESS });
const signature = signSep53(challenge); // see Quickstart, step 3
({ session } = await post('/auth/verify', { address: ADDRESS, challenge, signature }));
return session.token;
}
async function post(path, body, auth) {
const res = await fetch(API + path, {
method: 'POST',
headers: { 'Content-Type': 'application/json', ...(auth ? { Authorization: 'Bearer ' + auth } : {}) },
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error.message), { code: data.error.code, status: res.status });
return data;
}import time, requests
API = "https://stellar-split-sooty.vercel.app/v1"
session = None
def token():
global session
if session and time.time() < session["exp"] - 60:
return session["token"]
ch = requests.post(f"{API}/auth/challenge", json={"address": ADDRESS}, timeout=15).json()["challenge"]
sig = sign_sep53(ch) # see Quickstart, step 3
s = requests.post(f"{API}/auth/verify", json={"address": ADDRESS, "challenge": ch, "signature": sig}, timeout=15).json()["session"]
from datetime import datetime
session = {"token": s["token"], "exp": datetime.fromisoformat(s["expiresAt"].replace("Z", "+00:00")).timestamp()}
return session["token"]Invite links and deep links
POST /v1/groups/:id/invites returns an inviteUrl of the form:
https://stellar-split-sooty.vercel.app/invite/<code>
The web app also serves /join/<code> for the same code. Opening either link asks the person to connect Freighter and sign in, then calls POST /v1/invites/:code/accept. An invite created with address works only for that wallet. An unbound invite works for anyone who has the code, so share it only with the group.
| App route | What it opens |
|---|---|
/invite/:code, /join/:code | Join a group |
/groups/:id | A group (members only) |
/groups/:id/settle/:memberId | Settle up with one member |
/groups/:id/activity | Expenses and payments |
Verify a settlement on chain
Each settlement carries txHash. Activity items also carry an explorerUrl. You can check a payment yourself without trusting the API:
# The transaction: memo_type must be "hash" and memo the intent memo (base64 on Horizon)
curl -sS https://horizon-testnet.stellar.org/transactions/$TX_HASH
# Its payments: asset, from, to and amount
curl -sS https://horizon-testnet.stellar.org/transactions/$TX_HASH/operationsconst H = 'https://horizon-testnet.stellar.org';
const tx = await (await fetch(H + '/transactions/' + txHash)).json();
const ops = await (await fetch(H + '/transactions/' + txHash + '/operations')).json();
// The intent memo is hex; Horizon shows hash memos in base64
const memoHex = Buffer.from(tx.memo, 'base64').toString('hex');
const pay = ops._embedded.records.find((o) => o.type === 'payment');
console.log(tx.successful, tx.memo_type, memoHex, pay.asset_code, pay.from, pay.to, pay.amount);import base64, requests
H = "https://horizon-testnet.stellar.org"
tx = requests.get(f"{H}/transactions/{tx_hash}", timeout=15).json()
ops = requests.get(f"{H}/transactions/{tx_hash}/operations", timeout=15).json()
memo_hex = base64.b64decode(tx["memo"]).hex()
pay = next(o for o in ops["_embedded"]["records"] if o["type"] == "payment")
print(tx["successful"], tx["memo_type"], memo_hex, pay["asset_code"], pay["from"], pay["to"], pay["amount"])In a browser, open https://stellar.expert/explorer/testnet/tx/<txHash>. Horizon prints amounts with 7 decimals (21.0000000), the API with at least 2 (21.00).
CORS
The API answers CORS only for origins in its ALLOWED_ORIGINS setting (by default the app's own APP_URL). In production the web app and the API share one origin, so a browser app on another origin gets no CORS headers and its requests are blocked. Call the API from your backend instead.
| Header | Value for an allowed origin |
|---|---|
Access-Control-Allow-Methods | GET, POST, PATCH, DELETE, OPTIONS |
Access-Control-Allow-Headers | authorization, content-type, idempotency-key, payment-signature |
Access-Control-Expose-Headers | payment-required, payment-response |
Webhooks Planned
The API sends no webhooks. To react to new activity, poll GET /v1/groups/:id/activity at a modest interval.
OpenAPI and SDKs Planned
There is no published OpenAPI file and no SDK package. Use plain HTTP as shown in these docs.