HTTP API
Referencia de las rutas implementadas en tilcai-infrastructure. La disponibilidad depende del entorno y de los módulos de tu instancia.
Autenticación
Authorization: Bearer YOUR_KEY. Las claves de tenant aíslan recursos y scopes. Vault, monitor y estado del relayer son rutas de operador. /health y /ready son públicas; el webhook del relayer usa firma propia.
curl "$TILCAI_API_URL/v1/routes" \
-H "Authorization: Bearer $TILCAI_API_KEY"Rutas por recurso
| Método | Ruta | Requisito |
|---|---|---|
| GET | /health | Sin Bearer · liveness: 200 mientras el proceso vive |
| GET | /ready · ?mode=transactional | Sin Bearer · readiness: 200 o 503 con cada comprobación |
| 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 | Operador |
| GET | /v1/monitor/events · /stream · /resources | Operador · prefijo /v1/monitor |
Liveness y readiness
/health responde 200 mientras el proceso vive, aunque el relayer esté caído: así la plataforma no reinicia el contenedor por una dependencia externa. /ready dice si la instancia puede hacer lo que promete su modo. En solo lectura exige la base de datos. En modo transaccional exige además un relayer que responda y acepte la clave, y que cada relayer que usa la instancia exista en la red y el tipo esperados, sin pausar y con firmante; también el submitter de Stellar y, en all-in-one, un worker con rondas recientes. Cada respuesta lista sus comprobaciones sin secretos y se reutiliza 5 s. ?mode=transactional hace esas comprobaciones en una instancia mainnet todavía en solo lectura: es el paso previo a activar transacciones. No verifica roles on-chain.
Formato de una cotización
{
"sourceNetwork": "eip155:10143",
"destinationNetwork": "stellar:testnet",
"amount": "1.25",
"payTo": "REPLACE_WITH_VALID_STELLAR_ADDRESS"
}El destinatario del ejemplo es un marcador. Sustitúyelo por una dirección válida. El importe es una cadena decimal de USDC; las unidades atómicas se gestionan en la infraestructura.
Idempotencia y respuestas
Usa una clave estable por operación lógica en Idempotency-Key, de 8 a 128 caracteres alfanuméricos, guion o guion bajo. Los errores de dominio incluyen error.code, message y recovery; la API puede añadir detail. Consulta el mismo paymentId después de un timeout.
La disponibilidad depende de tu instancia. Consulta /health y /v1/routes antes de integrar.