API reference
Every route lives under src/app/api. None of them require an API key. Authorization is cookie-based: an authenticated session, an anonymous draft session, or nothing, depending on the route (see Authentication).
Auth
| Route | Method | Purpose |
|---|---|---|
/api/auth/challenge | POST | Issues a SEP-53 sign-in message and a matching JWT for a given public key. |
/api/auth/verify | POST | Verifies a signed challenge and issues a session plus a refresh token. |
/api/auth/session | GET | Returns the current authenticated public key, refreshing the session from the refresh token if needed. |
/api/auth/logout | POST | Revokes the current refresh token and clears both session cookies. |
Batches
| Route | Method | Purpose |
|---|---|---|
/api/batches | GET | Lists every batch visible to the current session (owned, or anonymous-drafted). |
/api/batches | POST | Creates a batch from parsed CSV text: network, optional asset, optional source account. |
/api/batches/[batchId] | GET | Fetches one batch with its recipients and attempts. |
/api/batches/[batchId] | PATCH | Updates a batch's network or asset. Only allowed before anything's been prepared. |
/api/batches/[batchId]/status | GET | A lightweight poll: just the batch status and each recipient's status, for refreshing a list view without the full payload. |
/api/batches/[batchId]/claim | POST | Attaches the connected wallet as owner and source account of an anonymously-drafted batch. Idempotent for the wallet that already owns it. |
/api/batches/[batchId]/recipients | PUT | Replaces the recipient list, diffing against the existing rows so unedited recipients keep their id. Blocked once a PaymentAttempt exists. |
/api/batches/[batchId]/checks | POST | Runs the bulk on-chain check (account existence, trustlines) against every still-pending recipient, or against a specific set of recipient ids if provided. |
/api/batches/[batchId]/prepare | POST | Builds the payment transaction(s) for every READY recipient. See Transaction building. |
/api/batches/[batchId]/submit | POST | Submits one signed (or pre-authorized) attempt and polls Stellar until it reaches a final state. |
/api/batches/[batchId]/retry | POST | Re-runs prepare/submit for only the FAILED recipients, leaving successful ones untouched. |
Address lists
| Route | Method | Purpose |
|---|---|---|
/api/address-lists | GET | Lists the current wallet's saved address lists. |
/api/address-lists | POST | Creates a new address list. |
/api/address-lists/[listId] | GET | Fetches one list with its entries. |
/api/address-lists/[listId] | PATCH | Renames a list or replaces its entries. |
/api/address-lists/[listId] | DELETE | Deletes a list. |
/api/address-lists/[listId]/start-batch | POST | Creates a new, already-claimed batch pre-filled from the list's entries. |
Balances and assets
| Route | Method | Purpose |
|---|---|---|
/api/check-balance | POST | Stateless bulk address, trustline, and balance lookup. Requires no wallet and creates nothing. |
/api/wallet/balances | GET | Returns the connected wallet's balances on the given network. |
/api/assets/icon | GET | Looks up an icon for a custom (not built-in) asset through its issuer's SEP-1 stellar.toml. |