Skip to main content
All FlowGuard products are backed by a single Express API. Frontend apps should point VITE_API_URL to this backend.

​
Base URL

http://localhost:3001/api
In production this points to your Railway (or equivalent) backend deployment.

​
Authentication

The API does not require tokens or sessions. Wallet identity is asserted via a single HTTP header: 
x-user-address: bchtest:qr...
Many protected routes (pause/cancel/approve/execute flows) require this header. Some create/build routes use explicit body fields instead, so always follow each endpoint’s request spec.

​
WalletConnect Transactions

Most on-chain build endpoints return a wcTransaction object rather than broadcasting directly. The frontend passes this to the connected wallet (Paytaca, Selene) via WalletConnect v2 using bch_signTransaction. After the wallet signs and broadcasts, the frontend calls the corresponding confirm-* endpoint with the resulting txHash. 
{
  "wcTransaction": {
    "transaction": "0200...",
    "sourceOutputs": [...],
    "broadcast": true,
    "userPrompt": "Fund vesting stream"
  }
}

​
Common Response Shape

Many endpoints include "success": true at the top level: 
{
  "success": true,
  "stream": { ... }
}
Some read/list endpoints return plain JSON arrays/objects without a success wrapper. Errors return a non-2xx status with "error" and optionally "message": 
{
  "error": "Stream not found"
}

​
Lifecycle Pattern

Most on-chain actions follow this two-step lifecycle:
1

Build

Call a build endpoint that returns a wallet payload (for example GET /api/streams/:id/funding-info, POST /api/streams/:id/claim, or POST /api/airdrops/:id/pause).
2

Confirm

After wallet broadcast, call the corresponding confirm-* endpoint with txHash. The backend verifies on-chain outputs and updates database state.
Non-transactional endpoints (for example list/get metadata routes) return data directly and do not use build/confirm. Some create endpoints (/api/streams/create, /api/payments/create, /api/airdrops/create) return deployment metadata first, then require a separate funding build call.

​
Status Values

Most stream/distribution resources share this status lifecycle:
StatusMeaning
PENDINGContract deployed, awaiting funding
ACTIVEFunded and live on-chain
PAUSEDTemporarily halted by authority
CANCELLEDTerminated early, funds returned
COMPLETEDAll obligations fulfilled
Proposal and governance entities use their own status enums (for example pending, approved, executed, rejected for treasury proposals).