Quickstart
You need a Stellar Testnet account and its key in a wallet or a local script. This page gets you from a health check to a signed-in request in under five minutes.
No account yet? Create one in Freighter set to Testnet, or with the Stellar Laboratory, then fund it with Friendbot: https://friendbot.stellar.org/?addr=YOUR_G_ADDRESS.
1. Check the API is up
curl -sS https://stellar-split-sooty.vercel.app/v1/healthconst res = await fetch('https://stellar-split-sooty.vercel.app/v1/health');
console.log(await res.json()); // { status: 'ok', network: 'testnet' }import requests
print(requests.get("https://stellar-split-sooty.vercel.app/v1/health", timeout=15).json())2. Ask for a sign-in challenge
Send your public G address. The API answers a text message that is valid for 5 minutes and works once.
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/auth/challenge" \
-H "Content-Type: application/json" \
-d '{"address":"GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI"}'const res = await fetch('https://stellar-split-sooty.vercel.app/v1/auth/challenge', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI"
}),
});
const data = await res.json();import requests
res = requests.post(
"https://stellar-split-sooty.vercel.app/v1/auth/challenge",
json={
"address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI"
},
timeout=15,
)
print(res.status_code, res.json()){
"challenge": "Stellar-Split sign-in\nAddress: GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI\nNonce: 3q2-v8Yc1kP0b5f9ZrT4mA.1793011500000.Xk...\nExpires: 2026-10-26T08:05:00.000Z",
"expiresAt": "2026-10-26T08:05:00.000Z"
}
3. Sign the challenge
The signature is SEP-53: ed25519 over sha256("Stellar Signed Message:\n" + challenge), sent as base64 or hex. In a browser, Freighter's signMessage does this. In a script, use the Stellar SDK with a Testnet-only key that you keep out of source control.
// Browser, with @stellar/freighter-api
import { signMessage } from '@stellar/freighter-api';
const { signedMessage } = await signMessage(challenge, { address });
// Node script, with @stellar/stellar-sdk and a Testnet key from the environment
import { Keypair } from '@stellar/stellar-sdk';
import { createHash } from 'node:crypto';
const kp = Keypair.fromSecret(process.env.TESTNET_SECRET); // never commit this
const digest = createHash('sha256').update('Stellar Signed Message:\n' + challenge).digest();
const signature = kp.sign(digest).toString('base64');# pip install stellar-sdk
import base64, hashlib, os
from stellar_sdk import Keypair
kp = Keypair.from_secret(os.environ["TESTNET_SECRET"]) # never commit this
digest = hashlib.sha256(("Stellar Signed Message:\n" + challenge).encode()).digest()
signature = base64.b64encode(kp.sign(digest)).decode()4. Exchange the signature for a session
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/auth/verify" \
-H "Content-Type: application/json" \
-d '{"address":"GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI","challenge":"<challenge text>","signature":"<base64 signature>"}'const res = await fetch('https://stellar-split-sooty.vercel.app/v1/auth/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
"challenge": "<challenge text>",
"signature": "<base64 signature>"
}),
});
const data = await res.json();import requests
res = requests.post(
"https://stellar-split-sooty.vercel.app/v1/auth/verify",
json={
"address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
"challenge": "<challenge text>",
"signature": "<base64 signature>"
},
timeout=15,
)
print(res.status_code, res.json()){
"session": {
"token": "eyJhIjoiR0FEV...In0.mR3k...",
"address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
"expiresAt": "2026-10-26T20:00:00.000Z"
}
}
Keep session.token. Send it as Authorization: Bearer <token>. It expires after 12 hours.
5. Create and list groups
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Lisbon trip","type":"trip"}'const res = await fetch('https://stellar-split-sooty.vercel.app/v1/groups', {
method: 'POST',
headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },
body: JSON.stringify({
"name": "Lisbon trip",
"type": "trip"
}),
});
const data = await res.json();import requests
res = requests.post(
"https://stellar-split-sooty.vercel.app/v1/groups",
headers={"Authorization": f"Bearer {token}"},
json={
"name": "Lisbon trip",
"type": "trip"
},
timeout=15,
)
print(res.status_code, res.json())curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/groups" \
-H "Authorization: Bearer $TOKEN"const res = await fetch('https://stellar-split-sooty.vercel.app/v1/groups', {
method: 'GET',
headers: { Authorization: 'Bearer ' + token },
});
const data = await res.json();import requests
res = requests.get(
"https://stellar-split-sooty.vercel.app/v1/groups",
headers={"Authorization": f"Bearer {token}"},
timeout=15,
)
print(res.status_code, res.json()){
"groups": [
{
"id": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
"name": "Lisbon trip",
"type": "trip",
"asset": "USDC",
"memberCount": 1,
"myNet": "0.00",
"updatedAt": "2026-10-26T07:40:00.000Z"
}
],
"totals": {
"youOwe": "0.00",
"youAreOwed": "0.00"
},
"otherTotals": []
}
Add an expense and read balances in the API reference, or learn the settlement flow in Concepts.