Pod Indexer SDK

A TypeScript/JavaScript SDK for interacting with the Pod Indexer API and WebSocket service. This SDK provides both HTTP and WebSocket clients for querying blockchain data, including transactions, logs, auctions, and contract information.

Table of Contents

• Installation
• Features
• HTTP Client
  • Initialization
  • Available Methods
  • Usage Examples
• WebSocket Client
  • Initialization
  • Usage Examples
• API Reference
• Error Handling
• TypeScript Support
• Contributing
• License

Installation

npm install @tapforce/pod-indexer-sdk

or

yarn add @tapforce/pod-indexer-sdk

or

pnpm add @tapforce/pod-indexer-sdk

Features

• HTTP Client: Query blockchain data with a comprehensive REST API
• WebSocket Client: Real-time blockchain event streaming via AWS API Gateway WebSockets
• TypeScript Support: Full TypeScript definitions for all APIs
• Error Handling: Robust error handling with detailed error messages
• Pagination: Built-in pagination support for list operations
• Filtering: Advanced filtering options for transactions, logs, and auctions
• Etherscan-like API: Compatible endpoints for contract verification data

HTTP Client

Initialization

import { PodIndexerHttpClient } from '@tapforce/pod-indexer-sdk';

const client = new PodIndexerHttpClient({
  apiKey: 'your-api-key',
  apiUrl: 'https://api.pod-indexer.com'
});

Available Methods

General Queries

• getTransactionsCount(params?) - Get total transaction count
• search(params) - Search for addresses, transactions, or contracts

Transactions

• getNormalTransactionsPage(params) - Get paginated transactions
• getNormalTransactionByHash(transactionHash) - Get transaction by hash
• getNormalDecodedTransactionsPage(params) - Get decoded transactions with function information
• getNormalDecodedTransactionByHash(transactionHash) - Get decoded transaction by hash

Logs

• getLogsPage(params) - Get paginated event logs
• getDecodedLogsPage(params) - Get decoded event logs with parameters

Auctions

• getAuctionsPage(params) - Get paginated auctions
• getAuctionInfo(params) - Get specific auction information
• getAuctionBidsPage(params) - Get auction bids
• getAuctionWinningBid(params) - Get winning bid for an auction
• getAuctionsCount(params) - Get auction count

Bridge & Verification

• getBridgeCertifiedLog(params) - Get certified log with merkle proof
• getEtherscanLikeVerifiedContractABI(contractAddress) - Get verified contract ABI
• getEtherscanLikeVerifiedContractSourceCode(contractAddress) - Get contract source code
• getEtherscanLikeContractCreation(contractAddresses) - Get contract creation information

Usage Examples

Get Transactions

import { PodIndexerHttpClient } from '@tapforce/pod-indexer-sdk';

const client = new PodIndexerHttpClient({
  apiKey: 'your-api-key',
  apiUrl: 'https://api.pod-indexer.com'
});

// Get paginated transactions
const transactions = await client.getNormalTransactionsPage({
  take: 10,
  skip: 0,
  address: '0x1234567890123456789012345678901234567890',
  sort: 'DESC'
});

console.log(transactions.result); // Array of transactions

// Get specific transaction
const transaction = await client.getNormalTransactionByHash(
  '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
);

console.log(transaction.result); // Transaction details

Get Decoded Transactions

// Get decoded transactions with function call information
const decodedTransactions = await client.getNormalDecodedTransactionsPage({
  take: 20,
  skip: 0,
  address: '0x1234567890123456789012345678901234567890',
  fromTimestamp: Date.now() - 86400000, // Last 24 hours
  toTimestamp: Date.now()
});

decodedTransactions.result?.forEach(tx => {
  console.log('Function:', tx.decoded?.function?.method);
  console.log('Parameters:', tx.decoded?.function?.parameters);
});

Query Event Logs

// Get event logs
const logs = await client.getLogsPage({
  take: 50,
  skip: 0,
  address: '0xContractAddress',
  topic0: '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef' // Transfer event
});

// Get decoded logs
const decodedLogs = await client.getDecodedLogsPage({
  take: 50,
  skip: 0,
  address: '0xContractAddress'
});

decodedLogs.result?.forEach(log => {
  console.log('Event:', log.decoded?.event);
  console.log('Parameters:', log.decoded?.parameters);
});

Search

// Search for addresses, transactions, or contracts
const searchResults = await client.search({
  pattern: '0x1234',
  everyGroupLimit: 10
});

console.log('Addresses:', searchResults.result?.addresses);
console.log('Transactions:', searchResults.result?.transactions);
console.log('Contracts:', searchResults.result?.contracts);

Auction Queries

// Get active auctions
const auctions = await client.getAuctionsPage({
  contractAddress: '0xAuctionContract',
  take: 10,
  skip: 0,
  filter: 'ACTIVE'
});

// Get auction bids
const bids = await client.getAuctionBidsPage({
  contractAddress: '0xAuctionContract',
  topic1: '0x...',
  topic3: '0x...',
  take: 20,
  skip: 0
});

// Get winning bid
const winningBid = await client.getAuctionWinningBid({
  contractAddress: '0xAuctionContract',
  topic1: '0x...',
  topic3: '0x...'
});

Contract Verification

// Get contract ABI
const abiResponse = await client.getEtherscanLikeVerifiedContractABI(
  '0xContractAddress'
);
const abi = JSON.parse(abiResponse.result);

// Get contract source code
const sourceCode = await client.getEtherscanLikeVerifiedContractSourceCode(
  '0xContractAddress'
);

console.log('Compiler Version:', sourceCode.result?.[0]?.CompilerVersion);
console.log('Source Code:', sourceCode.result?.[0]?.SourceCode);

// Get contract creation info
const creationInfo = await client.getEtherscanLikeContractCreation([
  '0xContract1',
  '0xContract2'
]);

creationInfo.result?.forEach(info => {
  console.log('Creator:', info.contractCreator);
  console.log('Tx Hash:', info.txHash);
});

WebSocket Client

WS Initialization

import { PodIndexerWsClient } from '@tapforce/pod-indexer-sdk';

const wsClient = new PodIndexerWsClient({
  appId: 'your-app-id',
  region: 'us-east-2',
  stage: 'production',
  apiKey: 'your-api-key',
  // Optional configurations
  pingIntervalMs: 30000, // Default: 30 seconds
  maxReconnectAttempts: 5, // Default: 5
  reconnectDelayMs: 2000 // Default: 2 seconds
});

WS Usage Examples

Connect and Subscribe

import { PodIndexerWsClient } from '@tapforce/pod-indexer-sdk';

const wsClient = new PodIndexerWsClient({
  appId: 'your-app-id',
  region: 'us-east-2',
  stage: 'production',
  apiKey: 'your-api-key'
});

// Connect to WebSocket
await wsClient.connect();

// Subscribe to topics
await wsClient.subscribe(['receipts', 'decodedReceipts']);

// Handle incoming events
wsClient.onEvent((data) => {
  console.log('Received event:', data);
});

// Handle connection events
wsClient.onConnect(() => {
  console.log('Connected to WebSocket');
});

wsClient.onDisconnect(() => {
  console.log('Disconnected from WebSocket');
});

// Unsubscribe from topics
await wsClient.unsubscribe(['receipts']);

// Disconnect
wsClient.disconnect();

Send Custom Commands

// Send custom commands to specific routes
await wsClient.sendToRoute('command', {
  command: 'custom-action',
  data: { foo: 'bar' }
});

API Reference

Types

The SDK exports all TypeScript types for requests and responses:

import {
  // Request types
  PaginationRequest,
  NormalTransactionsRequest,
  LogsRequest,
  TransactionCountRequest,
  AuctionBidsRequest,
  AuctionSingleRequest,
  AuctionsRequest,
  SearchRequest,
  AuctionsCountRequest,
  BridgeCertifiedLogRequest,

  // Response types
  ApiResponse,
  NormalTransactionResponse,
  NormalDecodedTransactionResponse,
  LogResponse,
  LogDecodedResponse,
  AuctionResponse,
  AuctionBidResponse,
  CertifiedLogResponse,

  // Etherscan-like types
  EtherscanLikeContractSourceCode,
  EtherscanLikeContractCreationInfo,

  // Helper functions
  sourceCodeStringToJson,

  // WebSocket types
  PodWsClientConfig,
  EventCallback,
  ConnectionCallback,
  PodWsEventMessage,
  PodGatewayRequest
} from '@tapforce/pod-indexer-sdk';

Helper Functions

sourceCodeStringToJson

Converts Etherscan-like source code string to JSON object:

import { sourceCodeStringToJson } from '@tapforce/pod-indexer-sdk';

const sourceCodeResponse = await client.getEtherscanLikeVerifiedContractSourceCode(
  '0xContractAddress'
);

const sourceCodeJson = sourceCodeStringToJson(
  sourceCodeResponse.result?.[0]?.SourceCode
);

console.log(sourceCodeJson);

Error Handling

The SDK provides a custom HttpClientError class for HTTP errors:

import { PodIndexerHttpClient, HttpClientError } from '@tapforce/pod-indexer-sdk';

const client = new PodIndexerHttpClient({
  apiKey: 'your-api-key',
  apiUrl: 'https://api.pod-indexer.com'
});

try {
  const transaction = await client.getNormalTransactionByHash('invalid-hash');
} catch (error) {
  if (error instanceof HttpClientError) {
    console.error('Status:', error.status); // HTTP status code
    console.error('Status Text:', error.statusText); // HTTP status text
    console.error('Message:', error.message); // Error message
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions. All methods, parameters, and return types are fully typed for an excellent development experience.

// TypeScript will provide full autocomplete and type checking
const transactions = await client.getNormalTransactionsPage({
  take: 10,
  skip: 0,
  sort: 'DESC', // TypeScript knows this must be 'ASC' | 'DESC'
  address: '0x...'
});

// Response types are fully typed
const txHash = transactions.result?.[0]?.hash; // TypeScript knows this is a string

Examples

See the examples directory for more detailed usage examples:

• fetch-transaction.ts - HTTP client examples
• ws-connect.ts - WebSocket client examples

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC © Tapforce

Support

For issues, questions, or contributions, please visit:

• GitHub: https://github.com/tapforce/pod-indexer-sdk
• Issues: https://github.com/tapforce/pod-indexer-sdk/issues