API overview
The Merchant API stores plans and subscriptions and submits pulls to Soroban.
The Merchant API is the off-chain side of Orbit. The contract enforces the money movement. The API keeps the records that a dashboard, checkout and keeper need.
Base URL
The API is self-hosted from the monorepo:
cd Orbit/apps/backend
cp .env.example .env # add Supabase URL and service-role key
npm install
node index.js # http://localhost:3001| Variable | Purpose |
|---|---|
SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY | Database (schema in apps/backend/schema.sql) |
ORBIT_CONTRACT_ID | Contract to invoke |
SOROBAN_RPC_URL | Soroban RPC endpoint |
STELLAR_NETWORK_PASSPHRASE | Network the transactions are signed for |
Conventions
- JSON in and out. Send
Content-Type: application/json. - IDs are UUIDs. Wallets are Stellar strkeys.
usdc_amountis an integer in raw units (7 decimals), the same value the contract uses.- Timestamps are ISO 8601 UTC.
- Errors have the shape
{ "error": "message" }. See Errors.
Authentication
The MVP API has no API keys yet. Run it on a private network or behind your own auth proxy. Scoped secret keys are on the roadmap.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /plans | Create a plan |
GET | /plans/{id} | Retrieve a plan for checkout |
POST | /subscriptions | Record a subscription after the on-chain handshake |
GET | /subscribers | List a merchant's subscribers |
POST | /trigger-pull | Sign and submit pull_funds |