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

Concepts

The objects the API works with and the rules it enforces. Amounts are always decimal strings, never JSON numbers.

Groups

A group has a name (up to 80 characters), a type (flat, trip or other) and one settlement asset, USDC by default. The creator joins as the first member. Only members can see or change a group: a non-member gets 404, so group ids cannot be probed.

Members

A member is a Stellar address in a group, with kind human or agent, a display name (defaults to the short address) and a home currency. A group holds at most 50 members. You add members directly by address or with an invite link.

Expenses

An expense has a description (up to 200 characters), an amount, the member who paid (paidBy) and a split. Its source is manual, scan or agent; an expense created with an agent token is always agent.

Splits: equal and exact

{
  "type": "equal",
  "participants": [
    "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f"
  ]
}
{
  "type": "exact",
  "shares": [
    {
      "memberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "amount": "30.00"
    },
    {
      "memberId": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
      "amount": "12.00"
    }
  ]
}
  • Equal: participants must be distinct members. The remainder of the division (at most n minus 1 stroops) goes to the payer.
  • Exact: shares must name distinct members and add up to the amount, otherwise 422 SPLIT_MISMATCH with details.difference.
  • Amounts are positive, at most 7 decimals (one stroop is 0.0000001).

Balances

Each member has a net. Positive means the member is owed money, negative means the member owes. A group's nets sum to zero. GET /v1/groups/:id also returns myPosition with suggested transfers (owes and owed), computed by the shared suggestTransfers rule.

Settlement intents

Paying is two steps, so a payment is always tied to one reserved debt:

  1. Reserve. POST /v1/groups/:id/settlements/intents with { to, amount } returns an intent with payTo, a memo and expiresAt (10 minutes).
  2. Pay. Build a USDC payment to payTo for exactly amount, with the memo as MEMO_HASH and time bounds that end no later than expiresAt. Sign it in the wallet and submit it to Testnet.
  3. Record. POST /v1/groups/:id/settlements with { intentId, txHash }.

While an intent is reserved, nobody else can settle with its payer or its creditor in that group (409 INTENT_IN_PROGRESS), so two concurrent payments cannot overpay. An amount above what you owe is 422 OVERPAY. Cancel an intent you will not pay (for example after a rejected signature) with POST .../intents/:intentId/cancel.

StatusMeaning
reservedOpen, waiting for the payment
settledPayment verified and recorded
cancelledCancelled by the payer
expiredPast expiresAt. A payment that already reached the chain can still be recorded
needs_reviewThe payment arrived but no longer matches an open debt. Kept with its hash; an operator resolves it

Memos

The intent memo is a hash memo: sha256("stellar-split:intent:" + intentId) in hex. It ties the on-chain payment to one intent, so an older payment cannot settle a new debt.

Horizon verification

A settlement is recorded only when Horizon on Stellar Testnet shows a successful transaction that:

  • pays the group's asset from the payer's address to the creditor's address, for exactly the intent amount,
  • carries the intent memo as MEMO_HASH,
  • has time bounds that end no later than the intent expiry.

Each transaction hash is recorded once (409 DUPLICATE_TX). The failure codes are in Errors.

Spend policy

The server caps agents, not people. An agent cannot reserve an intent (or get dry-run terms) that would take it over 25 per payment, 50 in 24 hours or 200 in 30 days, counted over all its groups. The answer is 403 AGENT_CAP_PER_PAYMENT, AGENT_CAP_PER_DAY or AGENT_CAP_PER_MONTH with details: { limit, spent, window }. Caps are plain numbers in the group's asset: a EURC amount counts like the same number of USDC. Details on Agents.

Assets on Testnet

AssetIssuer (Testnet)Notes
USDCGBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5Circle Testnet USDC. Default for every group
EURCGB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVOCircle Testnet EURC. Offered only when the server sets EURC_ISSUER; otherwise 400 ASSET_NOT_SUPPORTED
  • Trustline. Both payer and creditor accounts need a trustline to the asset before a payment can arrive.
  • XLM for fees. Fund a new Testnet account with Friendbot: https://friendbot.stellar.org/?addr=G....
  • Test USDC and EURC. Get them from Circle's Testnet faucet at faucet.circle.com. It has a captcha and cannot be scripted.
Mainnet issuers are different

These are Testnet addresses. The API runs on Testnet only.

Last updated 26 October 2026Edit this page on GitHub