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_MISMATCHwithdetails.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:
- Reserve.
POST /v1/groups/:id/settlements/intentswith{ to, amount }returns an intent withpayTo, amemoandexpiresAt(10 minutes). - Pay. Build a USDC payment to
payTofor exactlyamount, with the memo asMEMO_HASHand time bounds that end no later thanexpiresAt. Sign it in the wallet and submit it to Testnet. - Record.
POST /v1/groups/:id/settlementswith{ 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.
| Status | Meaning |
|---|---|
reserved | Open, waiting for the payment |
settled | Payment verified and recorded |
cancelled | Cancelled by the payer |
expired | Past expiresAt. A payment that already reached the chain can still be recorded |
needs_review | The 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
| Asset | Issuer (Testnet) | Notes |
|---|---|---|
| USDC | GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 | Circle Testnet USDC. Default for every group |
| EURC | GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO | Circle 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.
These are Testnet addresses. The API runs on Testnet only.