IndexerClient: Query On-Chain Events and Manage Webhooks

IndexerClient is a thin HTTP client for a running @ankarachain/indexer service. It does not communicate with any blockchain directly — the indexer service handles chain polling and event normalization in the background. You use IndexerClient to query the event history it has indexed, and to manage webhook subscriptions that deliver new events to your application in real time.

Import

import { IndexerClient } from "@ankarachain/sdk";

Constructor

new IndexerClient(baseUrl: string)

string

required

The base URL of the running @ankarachain/indexer service, e.g. "http://localhost:4100" or "https://indexer.myapp.com". A trailing slash is stripped automatically.

import { IndexerClient } from "@ankarachain/sdk";

const indexer = new IndexerClient("http://localhost:4100");

Methods

`queryEvents`

queryEvents(filter?: EventQueryFilter): Promise<IndexedEvent[]>

Queries the indexer for on-chain events matching the given filter. Returns events oldest-first. Omitting filter (or passing an empty object) returns all indexed events up to the default limit.

string

Filter to events emitted by a specific contract address.

string

Filter by event type name, e.g. "opened", "liquidat", "delivered". Partial string matching may vary by indexer configuration.

number

Unix timestamp — only return events with timestamp >= since.

number

Maximum number of events to return. The indexer may cap this at its own configured maximum.

Returns: Promise<IndexedEvent[]>

string

Unique event identifier assigned by the indexer.

string

Address of the contract that emitted the event.

string

Normalized event type string, e.g. "opened", "funded", "liquidated".

number

Ledger number (Stellar) or block number (EVM) the event was included in.

string

Transaction hash of the transaction that emitted the event.

number

Unix timestamp of the ledger/block.

unknown

Event-specific decoded payload. Shape varies by event type — see the indexer service documentation for per-event schemas.

// All events for a specific vault contract
const events = await indexer.queryEvents({
  contract: vaultContractId,
  limit:    50,
});

// Loan-open events from the last 24 hours
const since = Math.floor(Date.now() / 1000) - 86_400;
const openEvents = await indexer.queryEvents({
  contract: vaultContractId,
  type:     "opened",
  since,
});

openEvents.forEach(e => {
  console.log(`Loan opened in tx ${e.txHash} at ledger ${e.ledger}`);
  console.log("Event data:", e.data);
});

`registerWebhook`

registerWebhook(url: string, events: string[]): Promise<RegisteredWebhook>

Registers a new webhook subscription. The indexer will POST a JSON payload to url whenever any of the specified event types are indexed. The response includes a secret field — store it immediately, as it is shown only once and never returned again by listWebhooks().

string

required

The HTTPS endpoint to deliver event payloads to, e.g. "https://myapp.com/hooks/ankara".

string[]

required

Array of event type names to subscribe to, e.g. ["opened", "liquidated"]. Pass ["*"] to subscribe to all event types.

Returns: Promise<RegisteredWebhook>

string

Unique webhook ID. Use this to delete the webhook later.

string

The delivery URL as registered.

string[]

The event type list as registered.

string

A signing secret shown exactly once at registration time. The indexer includes this in an X-Ankara-Signature header on every delivery so you can verify the payload’s authenticity. Store it securely — it is not returned by listWebhooks().

number

Unix timestamp of webhook creation.

const webhook = await indexer.registerWebhook(
  "https://myapp.com/hooks/ankara",
  ["opened", "liquidated", "funded", "delivered"]
);

// Store the secret — you won't see it again!
await db.saveWebhookSecret(webhook.id, webhook.secret!);
console.log("Webhook ID:", webhook.id);

The secret field is returned only in the response from registerWebhook(). It is absent from all subsequent calls, including listWebhooks(). If you lose it, you must delete and re-register the webhook.

`listWebhooks`

listWebhooks(): Promise<RegisteredWebhook[]>

Returns all registered webhooks. The secret field is not included in this response — only the id, url, events, and createdAt fields are returned.

const webhooks = await indexer.listWebhooks();
webhooks.forEach(wh => {
  console.log(`${wh.id}: ${wh.url} — watching: ${wh.events.join(", ")}`);
});

`removeWebhook`

removeWebhook(webhookId: string): Promise<boolean>

Deletes a registered webhook by its ID. Returns true if the webhook was successfully removed.

string

required

The id of the webhook to remove, as returned by registerWebhook() or listWebhooks().

const removed = await indexer.removeWebhook("wh_abc123");
console.log("Removed:", removed); // true

Full Example

import { IndexerClient } from "@ankarachain/sdk";

const indexer = new IndexerClient("https://indexer.myapp.com");

// ── Query recent escrow events ───────────────────────────────────────────
const escrowEvents = await indexer.queryEvents({
  contract: escrowContractAddress,
  since:    Math.floor(Date.now() / 1000) - 7 * 86_400, // last 7 days
  limit:    100,
});

console.log(`Found ${escrowEvents.length} escrow events`);

// ── Register a webhook for vault liquidations ────────────────────────────
const webhook = await indexer.registerWebhook(
  "https://myapp.com/api/hooks/vault-alerts",
  ["liquidated", "opened"]
);

// Store the secret securely for signature verification
process.env.WEBHOOK_SECRET = webhook.secret!;
console.log("Webhook registered:", webhook.id);

// ── List all webhooks ────────────────────────────────────────────────────
const all = await indexer.listWebhooks();
console.log("Active webhooks:", all.length);

// ── Clean up a webhook ───────────────────────────────────────────────────
await indexer.removeWebhook(webhook.id);

Webhook Payload Verification

The indexer signs every delivery with a X-Ankara-Signature header. Verify it in your webhook handler using the secret you saved at registration time.

import crypto from "crypto";

function verifyWebhookSignature(
  rawBody: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

// Example Express handler
app.post("/api/hooks/vault-alerts", express.raw({ type: "*/*" }), (req, res) => {
  const signature = req.headers["x-ankara-signature"] as string;
  const isValid   = verifyWebhookSignature(req.body.toString(), signature, secret);

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log("Verified event:", event.eventType);
  res.sendStatus(200);
});

Type Reference

interface EventQueryFilter {
  contract?: string;   // Filter by contract address
  type?:     string;   // Filter by event type name
  since?:    number;   // Unix timestamp lower bound
  limit?:    number;   // Max results to return
}

interface IndexedEvent {
  id:        string;
  contract:  string;
  eventType: string;
  ledger:    number;
  txHash:    string;
  timestamp: number;
  data:      unknown;
}

interface RegisteredWebhook {
  id:        string;
  url:       string;
  events:    string[];
  /** Present only in the registerWebhook() response — not returned by listWebhooks(). */
  secret?:   string;
  createdAt: number;
}

SDK

Types & Config

Contracts

Stellar modules

IndexerClient: Query On-Chain Events and Manage Webhooks

Import

Constructor

Methods

`queryEvents`

`registerWebhook`

`listWebhooks`

`removeWebhook`

Full Example

Webhook Payload Verification

Type Reference

​Import

​Constructor

​Methods

​queryEvents

​registerWebhook

​listWebhooks

​removeWebhook

​Full Example

​Webhook Payload Verification

​Type Reference

Import

Constructor

Methods

`queryEvents`

`registerWebhook`

`listWebhooks`

`removeWebhook`

Full Example

Webhook Payload Verification

Type Reference