Stellar Testnet only. No real money moves. What this means

Authentication

People sign in with their Stellar wallet. Agents use a token that the operator issues. Both send Authorization: Bearer <token>. There are no API keys for third parties.

Wallet sign-in (people)

  1. POST /v1/auth/challenge with { "address": "G..." } returns { challenge, expiresAt }.
  2. The wallet signs the challenge text with SEP-53: ed25519 over sha256("Stellar Signed Message:\n" + challenge). Freighter's signMessage does this.
  3. POST /v1/auth/verify with { address, challenge, signature } (base64 or hex) returns { session: { token, address, expiresAt } }.
  4. Send the token on every call: Authorization: Bearer <token>.

Challenge format

Stellar-Split sign-in
Address: G...
Nonce: <id>.<expiry ms>.<hmac>
Expires: 2026-10-26T08:05:00.000Z

The API checks that the text is exactly the one it issued for that address, that it has not expired, that the signature verifies against the address, and then burns the nonce. A second verify with the same challenge fails with 401 UNAUTHORIZED.

Sessions

PropertyValue
Challenge lifetime5 minutes, single use
Session lifetime12 hours (expiresAt in the verify response)
FormatHMAC-SHA256 signed with the server SESSION_SECRET. Stateless, so it works across serverless instances
RenewalNone. Sign in again when it expires
LogoutDrop the token on the client. There is no server-side revoke for human sessions

The web app keeps the token in localStorage until it expires, and removes it on disconnect or account change.

Agent tokens

An agent authenticates with a random token issued by the operator. The API stores only its SHA-256, mapped to the agent's Stellar address, in the AGENT_TOKENS environment variable (sha256hex=GADDRESS pairs, comma separated).

TOKEN=$(openssl rand -base64 32)
printf %s "$TOKEN" | sha256sum     # the hash goes into AGENT_TOKENS on the API
# the token itself goes only into that agent's MCP server environment
  • An agent token has no expiry. Revoke it by removing its hash from AGENT_TOKENS and redeploying.
  • Agent routes for linking (/v1/agents/link*, /v1/me/agents) answer 403 FORBIDDEN to an agent: only a signed-in person can manage links.
  • Agents are capped per payment, per 24 hours and per 30 days. See spend policy.

Headers

HeaderUse
Authorization: Bearer <token>Every route except GET /v1/health, POST /v1/auth/challenge and POST /v1/auth/verify
Content-Type: application/jsonPOST and PATCH bodies. Bodies must be a JSON object
Idempotency-KeyOptional on POST /v1/groups/:id/expenses. 8 to 64 letters, digits, - or _
PAYMENT-SIGNATUREOnly on the x402-style intent route, see the API reference

Keep secrets off the client

Never send a secret key

Any request body that contains something shaped like a Stellar secret key (S plus 55 base32 characters) is refused with 400 SECRET_KEY_REJECTED, before parsing and again after, so JSON escapes do not get past it. Sign in the wallet, send only signatures and public addresses.

  • Keep agent tokens and MCP_AUTH_TOKEN on servers. Never ship them in a browser bundle or a mobile app.
  • Session tokens are bearer credentials. Send them only over HTTPS to the API origin.
  • The Supabase service role key lives only in the API. The browser gets no database credential.
Last updated 26 October 2026Edit this page on GitHub