Solver API

API reference

The solver API is served by the t3rn smart-contract hub and proxied through api.t3rn.io. Full OpenAPI spec and interactive playground ship with the next portal release.

Authentication

All solver endpoints require a Bearer token issued by the t3rn smart-contract hub after completing wallet verification (SIWE). Tokens expire after 24 hours and are non-transferable.

Authorization: Bearer <your-solver-token>

Mint a token by signing in with your registered solver wallet at /solve/register

Core endpoints

SSE/api/solver/stream

Subscribe to the real-time intent + genome event stream. Use this to receive intents and bid against them in real time.

Reconnect with exponential backoff.

POST/api/solver/bid

Submit a bid for an open intent. Must arrive within the bidWindow. EIP-712 signed by your executor address.

GET/api/solver/leaderboard

Aggregated solver rankings for the given window (24h / 7d / 30d / all). Returns fills, earnings, success rate, and p50 latency.

Query: ?window=24h

GET/api/solver/orders

Orders won by the authenticated solver. Supports pagination and status filter.

Query: ?page=1&status=settled

GET/api/solver/payouts

Payout history for the authenticated solver. Each row includes tx hash, chain, asset, amount, and timestamp.

POST/api/solver/webhook

Genome SSE stream

Subscribe to the real-time intent stream. The server emits a newline-delimited JSON event for each new intent, settled order, or agent action. Solvers bid against the stream in real-time.

GET /api/solver/stream
Accept: text/event-stream
Authorization: Bearer <token>

// Each event:
data: {"kind":"order","id":"T:1714/order:0xabc","asset":"ETH","amount":"1.25","from":"ethereum","to":"base","minFill":"1.24"}

Heartbeat

30s

Max backlog

250 events

Reconnect

Auto (exp. backoff)

Submitting a bid

Bids must arrive within the intent's bidWindow (default 800ms). The winning bid is the one with the highest fill amount that also satisfies the minimum fill threshold and passes on-chain verification.

POST /api/solver/bid

{
  "intentId": "T:1714/order:0xabc",
  "fillAmount": "1.245",          // must be ≥ minFill
  "executorAddress": "0x...",     // your hot wallet
  "signature": "0x..."            // EIP-712 over {intentId, fillAmount, executorAddress}
}

Webhooks

Register a HTTPS endpoint via the solver API to receive push notifications for won bids, settled orders, and payout confirmations. All deliveries include an X-T3rn-Signature header (HMAC-SHA256 over the raw body).

solver.bid.wonYour bid was selected as the fill

solver.bid.lostAnother solver won the intent

order.settledCross-chain settlement confirmed on-chain

order.refundedIntent refunded to the user

payout.confirmedSolver earnings transferred to executor wallet

Rate limits

EndpointLimitWindow

POST /api/solver/bid500 / minrolling 60s

GET /api/solver/stream10 connsper token

GET /api/solver/*300 / minrolling 60s

POST /api/solver/webhook10 / daycalendar day

Exceeding the limit returns HTTP 429. Retry-After header is included.