Testnet · chain 6
Open app
  1. Docs
  2. Developers
  3. Indexer API

Developers

Indexer API

Query reconciled operations and understand the authenticated partner boundary.

Revision 62 min read
On this page
  1. Public reads
  2. Ingestion checks
  3. Partner APIs
  4. Webhook delivery

The Go service continuously ingests recognized Trust Stack events into PostgreSQL and exposes bounded read endpoints. It is a discovery and integration layer, not a transaction signer.

Public reads#

The public surface includes health/readiness, operation discovery, token-lock and vesting reads, and product-specific indexed collections used by the dApp and marketing proof pages.

EndpointReturns
GET /healthz, GET /readyzprocess health and database readiness
GET /v1/operations, GET /v1/operations/{eventHash}reconciled operation events
GET /v1/fixed-locks, GET /v1/fixed-locks/{vault}token locks
GET /v1/vesting, GET /v1/vesting/{vault}vesting schedules
GET /v1/payment-streamspayment streams
GET /v1/staking-positionsstaking positions
GET /v1/airdrop-campaigns, GET /v1/airdrop-claimsMerkle airdrop campaigns and claims
GET /v1/digital-asset-locksDigital Asset locks
GET /v1/lp-locksDexlyn LP locks
GET /v1/balances/eventsa server-sent event stream of native SUPRA balance refresh hints for one account
POST /v1/digital-assets, GET /v1/digital-assets/media/{digest}, GET /v1/digital-assets/metadata/{digest}Digital Asset media upload (at most 5 MiB) and the content-addressed media and metadata it publishes

Position collections accept role filters (creator, beneficiary, or participant, plus product-specific filters such as staker or recipient), a lifecycle status, and page and limit (at most 100) parameters. Each record carries the originating packageAddress and its moduleVersion, so revision-6 positions (module version 4) are distinguishable from claim-only revision-5 and earlier positions. The dApp's My positions table reads these collections.

List endpoints enforce bounded limits, deterministic ordering, validated filters, and pagination. Treat response schemas as versioned contracts; the canonical OpenAPI document lives at apps/indexer-api/api/openapi.yaml.

Ingestion checks#

  • configured chain ID must match the Supra response header;
  • only exact registered package/module/event types are accepted;
  • unknown fields and malformed values fail strict parsing;
  • addresses and unsigned integers are canonicalized;
  • the event hash is cross-checked against its emission proof;
  • database writes are idempotent.

Partner APIs#

Authenticated partners may create idempotent operation intents and manage a bounded set of webhook destinations. API credentials and encrypted signing secrets are server-side only. Reusing an idempotency key with different semantics returns a conflict rather than silently changing the request.

Webhook delivery#

Deliveries are durable and at least once. Each destination receives an event-hash idempotency key, timestamp, and HMAC-SHA256 signature. Retries are capped. Redirects, proxy environment variables, private networks, loopback, link-local, carrier-grade NAT, documentation ranges, and DNS rebinding targets are rejected.

Consumers must verify the signature, enforce a timestamp window, and deduplicate by event hash.