HTTP API
Reference for routes implemented in tilcai-infrastructure. Availability depends on your instance environment and enabled modules.
Authentication
Authorization: Bearer YOUR_KEY. Tenant keys isolate resources and scopes. Vault, monitor and relayer status are operator routes. /health and /ready are public; the relayer webhook uses its own signature.
curl "$TILCAI_API_URL/v1/routes" \
-H "Authorization: Bearer $TILCAI_API_KEY"Resource routes
| Method | Path | Requirement |
|---|---|---|
| GET | /health | No Bearer · liveness: 200 while the process runs |
| GET | /ready · ?mode=transactional | No Bearer · readiness: 200 or 503 with each check |
| GET | /v1/routes | payments |
| POST | /v1/crosschain/quotes | payments |
| POST | /v1/crosschain/payments | payments · Idempotency-Key |
| GET | /v1/crosschain/payments/:id | payments |
| POST | /v1/crosschain/payments/:id/authorization | payments |
| POST | /v1/crosschain/payments/:id/burn | payments |
| POST | /v1/crosschain/payments/:id/reconcile | payments |
| POST / GET | /v1/accounts | accounts:write / accounts:read |
| GET | /v1/accounts/:id | accounts:read |
| GET / POST | /v1/vault / /v1/vault/disbursements | Operator |
| GET | /v1/monitor/events · /stream · /resources | Operator · /v1/monitor prefix |
Liveness and readiness
/health answers 200 while the process runs, even with the relayer down, so the platform does not restart the container over an external dependency. /ready says whether the instance can do what its mode promises. Read-only requires the database. Transactional mode also requires a relayer that answers and accepts the key, and every relayer the instance uses on its expected network and type, unpaused and with a signer; plus the Stellar submitter and, in all-in-one, a worker with recent rounds. Each answer lists its checks without secrets and is reused for 5 s. ?mode=transactional runs those checks on a mainnet instance that is still read-only: the step before enabling transactions. It does not verify on-chain roles.
Quote request shape
{
"sourceNetwork": "eip155:10143",
"destinationNetwork": "stellar:testnet",
"amount": "1.25",
"payTo": "REPLACE_WITH_VALID_STELLAR_ADDRESS"
}The example recipient is a placeholder. Replace it with a valid address. Amount is a decimal USDC string; atomic units are managed by the infrastructure.
Idempotency and responses
Use a stable Idempotency-Key for each logical operation: 8–128 alphanumeric, hyphen or underscore characters. Domain errors include error.code, message and recovery; the API may add detail. Query the same paymentId after a timeout.
Availability depends on your instance. Check /health and /v1/routes before integrating.