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

API reference

Base URL https://stellar-split-sooty.vercel.app/v1. JSON in, JSON out. Amounts are decimal strings. Errors are { "error": { "code", "message", "details"? } }. Examples use $TOKEN for your session token.

Not built yet

There are no /v1/approvals or /v1/agents/:id policy routes. Approvals and per-agent policies are planned. See Agents.

Meta

GET /v1/health

Liveness check.

Auth: None

Status codes
StatusCodeWhen
200API is up
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/health"
Response
{
  "status": "ok",
  "network": "testnet"
}

Auth

POST /v1/auth/challenge

Issues a SEP-53 sign-in message for an address. Valid 5 minutes, single use.

Auth: None

Parameters
NameInTypeRequiredDescription
addressbodystringYesStellar G address
Status codes
StatusCodeWhen
200Challenge issued
400INVALID_ADDRESSNot a valid G address
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/auth/challenge" \
  -H "Content-Type: application/json" \
  -d '{"address":"GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI"}'
Response
{
  "challenge": "Stellar-Split sign-in\nAddress: G...\nNonce: ...\nExpires: 2026-10-26T08:05:00.000Z",
  "expiresAt": "2026-10-26T08:05:00.000Z"
}

POST /v1/auth/verify

Exchanges a signed challenge for a 12-hour session.

Auth: None

Parameters
NameInTypeRequiredDescription
addressbodystringYesSame address as the challenge
challengebodystringYesThe exact challenge text
signaturebodystringYesSEP-53 signature, base64 or hex
Status codes
StatusCodeWhen
200Session issued
401UNAUTHORIZEDBad signature, address or challenge, expired, or already used
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"address":"GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI","challenge":"<challenge>","signature":"<base64>"}'
Response
{
  "session": {
    "token": "<token>",
    "address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "expiresAt": "2026-10-26T20:00:00.000Z"
  }
}

Profile

GET /v1/me

Your profile. Defaults when you have not saved one.

Auth: Bearer session or agent token

Status codes
StatusCodeWhen
200Profile
401UNAUTHORIZEDNo or expired token
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/me" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
  "displayName": null,
  "homeCurrency": "USD",
  "email": null
}

PATCH /v1/me

Updates your profile. Send only the fields you change.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
displayNamebodystringNoUp to 60 characters
homeCurrencybodystringNo3-letter code, for example EUR
emailbodystring | nullNoEmail or null
Status codes
StatusCodeWhen
200Updated profile
400VALIDATIONA field is invalid
Request
curl -sS -X PATCH "https://stellar-split-sooty.vercel.app/v1/me" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Ana","homeCurrency":"EUR"}'
Response
{
  "address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
  "displayName": "Ana",
  "homeCurrency": "EUR",
  "email": null
}

Groups and members

GET /v1/groups

Your groups with your net in each. totals covers USDC groups; otherTotals lists other assets separately, because dollars and euros never add up.

Auth: Bearer session or agent token

Status codes
StatusCodeWhen
200List
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/groups" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "groups": [
    {
      "id": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
      "name": "Lisbon trip",
      "type": "trip",
      "asset": "USDC",
      "memberCount": 3,
      "myNet": "-21.00",
      "updatedAt": "2026-10-26T07:55:00.000Z"
    }
  ],
  "totals": {
    "youOwe": "21.00",
    "youAreOwed": "0.00"
  },
  "otherTotals": []
}

POST /v1/groups

Creates a group. You join as the first member.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
namebodystringYesUp to 80 characters
typebodystringNoflat, trip or other (default)
assetbodystringNoUSDC (default) or EURC when enabled
displayNamebodystringNoYour name in this group
Status codes
StatusCodeWhen
201Group detail
400VALIDATIONBad name or field
400ASSET_NOT_SUPPORTEDAsset not configured on this server
Request
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"}'
Response
{
  "group": {
    "id": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "name": "Lisbon trip",
    "type": "trip",
    "asset": {
      "code": "USDC",
      "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
    },
    "network": "testnet",
    "createdAt": "2026-10-26T07:40:00.000Z"
  },
  "members": [
    {
      "id": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "kind": "human",
      "displayName": "GAAQ…OBQ2",
      "address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
      "homeCurrency": "EUR"
    }
  ],
  "me": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
  "balances": [
    {
      "memberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "net": "0.00"
    }
  ],
  "myPosition": {
    "net": "0.00",
    "owes": [],
    "owed": []
  },
  "expenseCount": 0
}

GET /v1/groups/:id

Group, members, balances and your suggested transfers.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
Status codes
StatusCodeWhen
200Group detail
404NOT_FOUNDMissing group or you are not a member
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "group": {
    "id": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "name": "Lisbon trip",
    "type": "trip",
    "asset": {
      "code": "USDC",
      "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
    },
    "network": "testnet",
    "createdAt": "2026-10-26T07:40:00.000Z"
  },
  "members": [
    {
      "id": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "kind": "human",
      "displayName": "GAAQ…OBQ2",
      "address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
      "homeCurrency": "EUR"
    }
  ],
  "me": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
  "balances": [
    {
      "memberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "net": "0.00"
    }
  ],
  "myPosition": {
    "net": "0.00",
    "owes": [],
    "owed": []
  },
  "expenseCount": 0
}

POST /v1/groups/:id/members

Adds a member by Stellar address.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
addressbodystringYesG address
displayNamebodystringNoDefaults to the short address
kindbodystringNohuman (default) or agent
Status codes
StatusCodeWhen
201Member added
400INVALID_ADDRESSBad address
400VALIDATIONGroup already has 50 members
409ALREADY_MEMBERAddress is already in the group
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC","displayName":"Rui"}'
Response
{
  "member": {
    "id": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
    "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "kind": "human",
    "displayName": "Rui",
    "address": "GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC",
    "homeCurrency": "USD",
    "createdAt": "2026-10-26T07:45:00.000Z"
  }
}

POST /v1/groups/:id/invites

Creates an invite link. With address, only that wallet can accept it.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
addressbodystringNoBind the invite to one G address
Status codes
StatusCodeWhen
201Invite created
400INVALID_ADDRESSBad address
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/invites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "inviteUrl": "https://stellar-split-sooty.vercel.app/invite/Zk3pQ9xR2mTa",
  "code": "Zk3pQ9xR2mTa"
}

POST /v1/invites/:code/accept

Joins the group of an invite. Safe to call twice.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
codepathstringYesInvite code
Status codes
StatusCodeWhen
200Joined, or already a member
404NOT_FOUNDUnknown invite, or bound to another address
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/invites/Zk3pQ9xR2mTa/accept" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
  "alreadyMember": false
}

Expenses and balances

GET /v1/groups/:id/expenses

Expenses, newest first.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
Status codes
StatusCodeWhen
200List
404NOT_FOUNDNot a member
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/expenses" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "expenses": [
    {
      "id": "e7c1...",
      "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
      "description": "Dinner",
      "amount": "42.00",
      "paidBy": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
      "split": {
        "type": "equal",
        "participants": [
          "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
          "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f"
        ]
      },
      "shares": [
        {
          "memberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
          "amount": "21.00"
        },
        {
          "memberId": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
          "amount": "21.00"
        }
      ],
      "source": "manual",
      "createdBy": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
      "createdAt": "2026-10-26T07:50:00.000Z"
    }
  ]
}

POST /v1/groups/:id/expenses

Records an expense with an equal or exact split. Repeating a request with the same Idempotency-Key in the group returns the first expense instead of a duplicate.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
Idempotency-KeyheaderstringNo8 to 64 of A-Z a-z 0-9 - _
descriptionbodystringYesUp to 200 characters
amountbodystringYesPositive, at most 7 decimals
paidBybodystringYesMember id
splitbodyobjectYes{ type: "equal", participants } or { type: "exact", shares: [{ memberId, amount }] }
sourcebodystringNomanual or scan; agents always get agent
Status codes
StatusCodeWhen
201Expense created
400VALIDATIONBad field or Idempotency-Key
422SPLIT_MISMATCHExact shares do not add up; see details.difference
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/expenses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: dinner-2026-10-26" \
  -H "Content-Type: application/json" \
  -d '{"description":"Dinner","amount":"42.00","paidBy":"c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f","split":{"type":"equal","participants":["a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c","c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f"]}}'
Response
{
  "expense": {
    "id": "e7c1...",
    "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "description": "Dinner",
    "amount": "42.00",
    "paidBy": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
    "split": {
      "type": "equal",
      "participants": [
        "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
        "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f"
      ]
    },
    "shares": [
      {
        "memberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
        "amount": "21.00"
      },
      {
        "memberId": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
        "amount": "21.00"
      }
    ],
    "source": "manual",
    "createdBy": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "createdAt": "2026-10-26T07:50:00.000Z"
  }
}

GET /v1/groups/:id/balances

Net per member with address and kind.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
Status codes
StatusCodeWhen
200Balances
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/balances" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "balances": [
    {
      "memberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "displayName": "Ana",
      "address": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
      "kind": "human",
      "net": "-21.00"
    },
    {
      "memberId": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
      "displayName": "Rui",
      "address": "GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC",
      "kind": "human",
      "net": "21.00"
    }
  ]
}

GET /v1/groups/:id/activity

Expenses and settlements together, newest first. Settlements include an explorerUrl.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
Status codes
StatusCodeWhen
200Items
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/activity" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "items": [
    {
      "id": "f2a1...",
      "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
      "from": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
      "to": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
      "amount": "21.00",
      "txHash": "3c9e...a1",
      "intentId": "0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e",
      "createdAt": "2026-10-26T08:01:12.000Z",
      "type": "settlement",
      "explorerUrl": "https://stellar.expert/explorer/testnet/tx/3c9e...a1"
    }
  ]
}

POST /v1/groups/:id/receipts/scan

Demo. Reads a receipt photo into a draft expense. Creates nothing. The photo and the reading are not stored. Use sample receipts only.

Auth: Bearer session or agent token, checked before the body is read

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
imageBase64bodystringYesJPEG, PNG or WebP, at most 1.4 million base64 characters
mimeTypebodystringYesimage/jpeg, image/png or image/webp
Status codes
StatusCodeWhen
200Draft
401UNAUTHORIZEDNo token
413VALIDATIONPhoto too large
422NOT_A_RECEIPTNot a receipt
422SCAN_UNREADABLETotal could not be read
429RATE_LIMITEDMore than 10 scans in 10 minutes
503SCAN_UNAVAILABLEReader not set up, down or out of quota
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/receipts/scan" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"imageBase64":"<base64>","mimeType":"image/jpeg"}'
Response
{
  "draft": {
    "merchant": "Cervejaria",
    "date": "2026-10-25",
    "currency": "USD",
    "total": "42.00",
    "usdc": "42.00",
    "items": [
      {
        "name": "Dinner",
        "amount": "42.00"
      }
    ],
    "warnings": []
  }
}

Settlements

POST /v1/groups/:id/settlements?dry_run=true

Payment terms for paying to, without reserving or recording anything. Agent caps apply.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
dry_runquerystringYestrue
tobodystringYesCreditor member id
amountbodystringYesAmount to pay
Status codes
StatusCodeWhen
200Terms
403AGENT_CAP_PER_PAYMENTOr _PER_DAY, _PER_MONTH
422OVERPAYMore than you owe
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/settlements?dry_run=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f","amount":"21.00"}'
Response
{
  "intent": {
    "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "from": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "to": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
    "amount": "21.00",
    "asset": {
      "code": "USDC",
      "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
    },
    "network": "stellar:testnet",
    "payFrom": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "payTo": "GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC"
  }
}

POST /v1/groups/:id/settlements/intents

Step 1: reserves a settlement intent for 10 minutes. An agent token may send onBehalfOf (its linked owner's member id) to pay the owner's debt from the agent account.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
tobodystringYesCreditor member id
amountbodystringYesAmount
onBehalfOfbodystringNoAgent only: owner member id
Status codes
StatusCodeWhen
201Intent reserved
403NOT_LINKEDAgent not linked to that member
403AGENT_CAP_PER_PAYMENTOr _PER_DAY, _PER_MONTH
409INTENT_IN_PROGRESSPayer or creditor has another reserved intent
422OVERPAYMore than you owe
503ASSET_UNAVAILABLEGroup asset not configured
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/settlements/intents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f","amount":"21.00"}'
Response
{
  "intent": {
    "id": "0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e",
    "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "from": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "to": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
    "amount": "21.00",
    "asset": {
      "code": "USDC",
      "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
    },
    "network": "stellar:testnet",
    "payFrom": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "payer": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "debtorMemberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "payTo": "GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC",
    "memo": {
      "type": "hash",
      "value": "9b1f...e4"
    },
    "status": "reserved",
    "reservedAt": "2026-10-26T08:00:00.000Z",
    "expiresAt": "2026-10-26T08:10:00.000Z"
  }
}

POST /v1/groups/:id/settlements

Step 2: records the payment once Horizon confirms it. to and amount may be sent and must match the intent.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
intentIdbodystringYesReserved intent id
txHashbodystringYesTestnet transaction hash
Status codes
StatusCodeWhen
201Settlement recorded
404INTENT_NOT_FOUNDNo such intent for you
409DUPLICATE_TXHash already recorded
409INTENT_NOT_OPENIntent settled or in review
409NEEDS_REVIEWPaid, but no longer matches an open debt
422PAYMENT_MISMATCHAnd the other verification codes in Errors
502UPSTREAM_UNAVAILABLEHorizon or the database did not answer; retry
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/settlements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"intentId":"0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e","txHash":"3c9e...a1"}'
Response
{
  "settlement": {
    "id": "f2a1...",
    "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "from": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "to": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
    "amount": "21.00",
    "txHash": "3c9e...a1",
    "intentId": "0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e",
    "createdAt": "2026-10-26T08:01:12.000Z"
  }
}

POST /v1/groups/:id/settlements/intents/:intentId/cancel

Cancels a reserved intent. Only its payer can cancel.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
intentIdpathstringYesIntent id
Status codes
StatusCodeWhen
200Cancelled intent
404INTENT_NOT_FOUNDNot yours or missing
409INTENT_NOT_OPENNot reserved any more
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/settlements/intents/0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e/cancel" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "intent": {
    "id": "0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e",
    "groupId": "6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88",
    "from": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "to": "c9d8e7f6-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
    "amount": "21.00",
    "asset": {
      "code": "USDC",
      "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
    },
    "network": "stellar:testnet",
    "payFrom": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "payer": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "debtorMemberId": "a3e1b7c2-0d4f-4e5a-8b9c-1d2e3f4a5b6c",
    "payTo": "GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC",
    "memo": {
      "type": "hash",
      "value": "9b1f...e4"
    },
    "status": "cancelled",
    "reservedAt": "2026-10-26T08:00:00.000Z",
    "expiresAt": "2026-10-26T08:10:00.000Z"
  }
}

POST /v1/groups/:id/settlements/intents/:intentId/x402

x402-style handshake for the intent payer, self-verified (no facilitator). Without PAYMENT-SIGNATURE: 402 with the terms in the body and, base64, in the PAYMENT-REQUIRED header. With it (base64 JSON { x402Version: 1, scheme: "exact", network: "stellar:testnet", payload: { txHash } }): the same Horizon check as step 2, then 200 with a PAYMENT-RESPONSE header. A payment that fails the check answers 402 again with error set.

Auth: Bearer session or agent token

Parameters
NameInTypeRequiredDescription
idpathstringYesGroup id
intentIdpathstringYesIntent id
PAYMENT-SIGNATUREheaderstringNoBase64 JSON with the transaction hash
Status codes
StatusCodeWhen
402Terms, or a failed check
200Settlement recorded
404INTENT_NOT_FOUNDNot the payer
409INTENT_NOT_OPENExpired or closed
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/settlements/intents/0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e/x402" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "x402Version": 1,
  "error": null,
  "accepts": [
    {
      "scheme": "exact",
      "network": "stellar:testnet",
      "asset": "USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
      "payTo": "GAVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUKRKFIVCUPVC",
      "amount": "21.00",
      "maxTimeoutSeconds": 540,
      "resource": "https://stellar-split-sooty.vercel.app/v1/groups/6f1c2a90-3b1e-4d7a-9a51-2f0c7e1d4b88/settlements/intents/0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e/x402",
      "extra": {
        "intentId": "0b6f7c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e",
        "memoType": "hash",
        "memo": "9b1f...e4",
        "expiresAt": "2026-10-26T08:10:00.000Z"
      }
    }
  ]
}

POST /v1/agents/link/challenge

Issues a link message for one of the operator's registered agent addresses. You sign it with SEP-53. Valid 5 minutes, single use.

Auth: Bearer session of a person (agent tokens get 403)

Parameters
NameInTypeRequiredDescription
agentAddressbodystringYesAgent G address, listed in AGENT_TOKENS
Status codes
StatusCodeWhen
200Link message
400INVALID_ADDRESSBad address
400VALIDATIONYour own address
400AGENT_NOT_REGISTEREDNot a registered agent
403FORBIDDENCalled with an agent token
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/agents/link/challenge" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentAddress":"GBRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWHOI2"}'
Response
{
  "message": "Stellar Split agent link\nOwner: GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI\nAgent: GBRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWHOI2\nNonce: ...\nExpires: 2026-10-26T08:05:00.000Z",
  "nonce": "...",
  "expiresAt": "2026-10-26T08:05:00.000Z"
}

POST /v1/agents/link

Links the agent to you with the signed message.

Auth: Bearer session of a person (agent tokens get 403)

Parameters
NameInTypeRequiredDescription
agentAddressbodystringYesAgent address
messagebodystringYesThe exact link message
signaturebodystringYesSEP-53 signature
Status codes
StatusCodeWhen
201Linked
400LINK_INVALIDBad, expired or reused signature
409AGENT_ALREADY_LINKEDAnother owner has an active link
Request
curl -sS -X POST "https://stellar-split-sooty.vercel.app/v1/agents/link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentAddress":"GBRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWHOI2","message":"<message>","signature":"<base64>"}'
Response
{
  "agent": {
    "address": "GBRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWHOI2",
    "ownerAddress": "GADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOZPI",
    "linkedAt": "2026-10-26T08:02:00.000Z"
  }
}

GET /v1/me/agents

Your linked agents, including revoked ones.

Auth: Bearer session of a person (agent tokens get 403)

Status codes
StatusCodeWhen
200List
403FORBIDDENAgent token
Request
curl -sS -X GET "https://stellar-split-sooty.vercel.app/v1/me/agents" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "agents": [
    {
      "address": "GBRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWHOI2",
      "linkedAt": "2026-10-26T08:02:00.000Z",
      "revokedAt": null
    }
  ]
}

DELETE /v1/me/agents/:address

Revokes a link.

Auth: Bearer session of a person (agent tokens get 403)

Parameters
NameInTypeRequiredDescription
addresspathstringYesAgent G address
Status codes
StatusCodeWhen
204Revoked, no body
404NOT_FOUNDNo active link
Request
curl -sS -X DELETE "https://stellar-split-sooty.vercel.app/v1/me/agents/GBRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWGY3DMNRWHOI2" \
  -H "Authorization: Bearer $TOKEN"
Response
// 204 No Content
Last updated 26 October 2026Edit this page on GitHub