SDK API Reference

This reference describes @tetherto/wdk-indexer-http@1.0.1. Start with the JavaScript SDK guide for installation and a complete request flow. The existing REST API reference documents direct HTTP access separately.

Exports

The package root exports these JavaScript values on Node.js and Bare:

import {
  WdkIndexerClient,
  WdkIndexerError,
  WdkIndexerApiError,
  WdkIndexerTimeoutError,
  WdkIndexerNetworkError,
  isApiError,
  BATCH_LIMIT,
} from '@tetherto/wdk-indexer-http';

CommonJS can access the same named exports with require('@tetherto/wdk-indexer-http'). The /bare export is an alias of the root. Node.js requires version 22 or later; Bare requires the optional peers.

TypeScript definitions ship with the package. Import types separately from JavaScript values:

import type {
  WdkIndexerClientConfig,
  TokenTransferOptions,
  BatchTokenBalanceRequest,
  BatchTokenTransferRequest,
  TransferFilters,
  WalletRegistration,
  WalletUpdate,
} from '@tetherto/wdk-indexer-http';

WdkIndexerClient

Construct a client with optional configuration:

const client = new WdkIndexerClient({ timeout: 30_000 });

Configuration

FetchLike receives a URL string and FetchInitLike containing method, headers, optional body, and signal. It returns a promise of FetchResponseLike with ok, status, statusText, and an asynchronous text() method. The client sends Accept: application/json and adds Content-Type: application/json when it sends a JSON body.

Input Handling

The client checks for a missing API key on authenticated calls. It does not validate batch sizes, chain/token support, addresses, filter ranges, or wallet payloads locally. The field constraints below describe the documented server contract. Blockchain and Token types provide known-name suggestions while accepting other strings; call getChains() for the current inventory.

Address path arguments are URL-encoded automatically. blockchain, token, txHash, and walletId path values are inserted as supplied. Use discovered chain/token keys and valid transaction or wallet identifiers; validate untrusted input before calling these methods. Reject path-control values such as . and .., and encode any permitted reserved characters before passing an otherwise valid identifier. Query fields set to null or undefined are omitted; zero values are retained.

Methods

All methods return promises. Paths below are relative to /api/v1. Only health() and getChains() omit authentication, even when the client has an API key.

health()

Takes no arguments. Returns the service's HealthResponse, with status ('healthy', 'degraded', or 'unhealthy') and ISO 8601 timestamp. Optional fields are deployEnvironment, deployedVersion, summary (healthy/unhealthy/total counts), and checks (dependency and per-indexer checks).

HTTP 503 with a non-null JSON body resolves instead of throwing. Inspect status to detect degraded service. An empty, null, or malformed 503 body throws WdkIndexerApiError. The client does not validate the parsed body's shape.

getChains()

Takes no arguments. Returns { chains: ChainInfo[] }. Each chain has name, tokens, and optional caseSensitive rules. Its address rule can be a boolean or regular-expression string; tx and block rules are optional booleans. Discover supported pairs at runtime instead of maintaining a static list.

getTokenTransfers()

Requires blockchain: Blockchain, token: Token, and address: string. Accepts optional TokenTransferOptions as the fourth argument. Returns { transfers: TokenTransfer[] } for the address; see response fields.

getTokenBalance()

Requires blockchain: Blockchain, token: Token, and address: string. Returns { tokenBalance: { blockchain, token, amount } }. amount is a decimal string in token base units.

getTransactionTransfers()

Requires blockchain: Blockchain, token: Token, and txHash: string. The documented transaction-hash limit is 255 characters. Returns { transfers: TokenTransfer[] }. The documented server behavior is HTTP 404 when the transaction is absent or has no transfers of that token; the client surfaces it as WdkIndexerApiError.

getBatchTokenTransfers()

Requires requests: BatchTokenTransferRequest[]: 1–10 items, each with blockchain, token, address, and optional TokenTransferOptions fields. Returns an array in request order; each item is { transfers: TokenTransfer[] } or ApiError. Use isApiError() to narrow each result. Failed items do not automatically reject an otherwise successful HTTP request.

getBatchTokenBalances()

Requires requests: BatchTokenBalanceRequest[]: 1–10 items, each with blockchain, token, and address. Returns an array in request order; each item is TokenBalanceResponse or ApiError. Whole-request failures still reject. See BATCH_LIMIT for application-side batching.

registerWallets()

Requires wallets: WalletRegistration[]: 1–10 registration records. Registers addresses for server-side transfer syncing. Returns { wallets: WalletRegistrationResult[] }, with a numeric status for each record.

The documented item statuses include 201 (created), 400 (invalid), and 429 (wallet quota reached). Inspect every item; the public type is number, not a closed status union. id, name, type, enabled, addresses, and meta are optional result fields. Failures can include error, and quota failures can include limit and currentCount. Do not assume an id exists merely because the HTTP call resolved.

listWallets()

Takes no arguments. Returns { wallets: Wallet[] } for the authenticated account. Use a returned id with the single-wallet methods.

getWallet()

Requires walletId: string. Returns one Wallet, without a wallet wrapper.

updateWallet()

Requires walletId: string and patch: WalletUpdate. The patch must contain name: string (1–100 characters), enabled: boolean, or both. Other fields are not part of the update contract. Returns the updated Wallet; enabled controls server-side syncing.

deleteWallet()

Requires walletId: string. Removes the registered wallet record and stops its syncing. Returns { success: boolean }. This is an Indexer operation, not an on-chain deletion.

getWalletTransfers()

Requires walletId: string; accepts optional TransferFilters. Returns { transfers: WalletTransfer[] } synced for that wallet. These records use ts, not the token-transfer endpoint's timestamp field.

getTransfers()

Accepts optional TransferFilters. Returns { transfers: WalletTransfer[] } synced across the authenticated account's registered wallets.

Request Types

TokenTransferOptions

Used by getTokenTransfers() and as fields of each BatchTokenTransferRequest:

TransferFilters

Used by getWalletTransfers() and getTransfers():

WalletRegistration

Response Fields

These are declared response shapes. The client parses JSON without runtime schema validation. An empty successful response resolves to null, even though the declared return types do not include it. A nonempty, invalid JSON success body throws WdkIndexerError.

TokenTransfer.timestamp, WalletTransfer.ts, Wallet.createdAt, and Wallet.updatedAt are Unix milliseconds. Transfer amounts are decimal strings in token base units. Keep them as strings or use BigInt for integer arithmetic. WalletTransfer.type is 'sent' or 'received'.

ApiError

An item error has required error: string and optional message: string and status: number. It is returned inside a successful batch response; it is not an instance of WdkIndexerApiError.

Errors

All package error classes extend WdkIndexerError, which extends Error. All methods can reject; missing keys, API errors, network failures, timeouts, and malformed responses are separate from batch-item errors.

For WdkIndexerApiError, errorType comes from a string body.error. The message uses a nonempty string body.message, otherwise the HTTP status and status text. body retains parsed JSON, raw text when parsing fails, or null for an empty body. The client does not retry automatically.

Helpers

isApiError()

isApiError(item: unknown): item is ApiError returns true for a non-null object with a string error property. It narrows batch result types; it is not a complete response-schema validator.

Batch Limit

BATCH_LIMIT is the number 10, representing the documented maximum for batch requests and registerWallets(). It is a convenience for callers. The client does not split arrays or enforce that maximum locally.

Next Steps

Need Help?