API Overview

Base URL: https://api.blockfinax.com/v1

Interactive Swagger: /v1/docs

OpenAPI 3.1 schema: /v1/openapi.json

Design

The API has two shapes of endpoint, organized by the URL prefix.

Read endpoints — plain REST

GET /v1/hedge/events/:chainId/:id
GET /v1/oracle/oracles/:chainId
GET /v1/governance/proposals/:chainId/:proposalId
GET /v1/pricing/health
...

Returns JSON wrapped in a data envelope. No auth required for any read. BigInt fields (token amounts, prices) are serialized as decimal strings so JSON doesn't lose precision.

Calldata-builder endpoints — POST /v1/tx/...

POST /v1/tx/hedge/buy-protection
POST /v1/tx/hedge/create-event
POST /v1/tx/oracle/submit-rate
POST /v1/tx/governance/diamond-cut
...

Returns a BuiltTx — { chainId, to, data, value, function, args, estimatedGas }. The server never signs anything. You sign with your own wallet (Privy, MetaMask, Rift, raw key) and broadcast via your own RPC, or via POST /v1/tx/broadcast if you'd rather not run one.

See the calldata-pattern explainer for the full integration flow.

Response envelope

Every successful response:

{
  "data": { ... },
  "meta": { ... }   // optional, only on paginated reads
}

Every error response:

{
  "error": {
    "code": "validation_error",
    "message": "Unsupported chainId 4242. Supported: 1135, 8453, 56",
    "details": [...]    // optional, for ZodErrors
  }
}

See Errors for the full taxonomy.

Supported chains

chainId	Network	symbol	Payment tokens
8453	Base	BASE	USDC
1135	Lisk	LISK	USDC
56	BNB Smart Chain	BSC	USDC, USDT

curl https://api.blockfinax.com/v1/chains

returns the live config — Diamond address, USDC address, USDT (where available), RPC URL, and payment-token decimals — for every supported chain.

Endpoint groups

Group	What it does	Auth
Meta	/me, /chains, /hedge/fees, owner / facet list	/me requires Rift bearer; others public
Hedge reads	Every read on the HedgeFacet — events, positions, deposits, capacity, quote-payout, protocol state	Public
Oracle reads	Oracle set, config, submissions	Public
Governance reads	Full Diamond Loupe (EIP-2535) + timelock proposal state	Public
Tx · build	Every state-changing contract function as a calldata builder	Public (server doesn't sign)
Tx · broadcast	Optional relay for pre-signed raw transactions	Public
Pricing	Fair-value quote (+ optional v8 attestation), engine health, signer	Public

Versioning + uptime

The API is at /v1. Breaking changes will go to /v2 with a deprecation window — endpoints in /v1 won't be removed without ≥6 months' notice through the OpenAPI changelog.