Skip to main content

Transaction History

The ONE SDK engine client provides APIs for fetching wallet transaction history with filtering, pagination, and real-time status tracking.

getWalletTransactions​

Fetch transaction history for a wallet address with optional filtering and pagination.

import { useOneClient } from '@one_deploy/sdk';

function TransactionList() {
  const { engineClient } = useOneClient();

  const loadHistory = async () => {
    const result = await engineClient.getWalletTransactions(
      '0x1234...abcd'
    );

    result.transactions.forEach((tx) => {
      console.log(`${tx.type}: ${tx.value} ${tx.currency} - ${tx.status}`);
    });
  };

  return <button onClick={loadHistory}>Load History</button>;
}

Method Signature​

getWalletTransactions(
  walletAddress: string,
  options?: TransactionQueryOptions
): Promise<TransactionPage>

Parameters:

ParameterTypeRequiredDescription
walletAddressstringYesThe wallet address to query.
optionsTransactionQueryOptionsNoFiltering and pagination options.

TransactionQueryOptions​

interface TransactionQueryOptions {
  /** Filter by transaction type. */
  type?: TransactionType | TransactionType[];

  /** Filter by transaction status. */
  status?: TransactionStatus | TransactionStatus[];

  /** Filter by chain ID. */
  chainId?: number;

  /** Number of transactions per page. Defaults to 20. Max 100. */
  limit?: number;

  /** Pagination cursor from a previous response. */
  cursor?: string;

  /** Start date filter (ISO 8601). */
  fromDate?: string;

  /** End date filter (ISO 8601). */
  toDate?: string;

  /** Sort order. Defaults to 'desc' (newest first). */
  sortOrder?: 'asc' | 'desc';
}

TransactionPage​

interface TransactionPage {
  /** Array of transactions for this page. */
  transactions: Transaction[];

  /** Cursor for the next page, or null if no more pages. */
  nextCursor: string | null;

  /** Total number of transactions matching the query (across all pages). */
  totalCount: number;
}

Transaction Type​

interface Transaction {
  /** Unique transaction identifier in the ONE SDK system. */
  id: string;

  /** On-chain transaction hash. */
  transactionHash: string;

  /** Type of transaction. */
  type: TransactionType;

  /** Current status. */
  status: TransactionStatus;

  /** Sender address. */
  fromAddress: string;

  /** Recipient address. */
  toAddress: string;

  /** Transaction amount as a decimal string. */
  value: string;

  /** Token symbol (e.g. 'ETH', 'USDC'). */
  currency: string;

  /** USD value at the time of the transaction. */
  valueUsd: string;

  /** Chain ID. */
  chainId: number;

  /** Gas fee paid in native token. */
  gasFee: string;

  /** Gas fee in USD. */
  gasFeeUsd: string;

  /** Block number the transaction was included in, or null if pending. */
  blockNumber: number | null;

  /** ISO 8601 timestamp. */
  timestamp: string;

  /** Block explorer URL. */
  explorerUrl: string;

  /** Optional memo or note. */
  memo: string | null;
}

type TransactionType =
  | 'send'
  | 'receive'
  | 'swap'
  | 'buy'
  | 'sell'
  | 'deposit'
  | 'withdraw'
  | 'bridge';

type TransactionStatus =
  | 'pending'
  | 'confirmed'
  | 'failed'
  | 'cancelled';

Pagination​

Use the cursor from each response to paginate through results.

import { useState, useCallback } from 'react';
import { useOneClient } from '@one_deploy/sdk';
import type { Transaction, TransactionPage } from '@one_deploy/sdk';

function PaginatedHistory({ walletAddress }: { walletAddress: string }) {
  const { engineClient } = useOneClient();
  const [transactions, setTransactions] = useState<Transaction[]>([]);
  const [nextCursor, setNextCursor] = useState<string | null>(null);
  const [totalCount, setTotalCount] = useState(0);
  const [loading, setLoading] = useState(false);

  const loadPage = useCallback(async (cursor?: string) => {
    setLoading(true);

    const page: TransactionPage = await engineClient.getWalletTransactions(
      walletAddress,
      {
        limit: 20,
        cursor,
        sortOrder: 'desc',
      }
    );

    setTransactions((prev) =>
      cursor ? [...prev, ...page.transactions] : page.transactions
    );
    setNextCursor(page.nextCursor);
    setTotalCount(page.totalCount);
    setLoading(false);
  }, [walletAddress, engineClient]);

  return (
    <div>
      <p>Total: {totalCount} transactions</p>

      {transactions.map((tx) => (
        <div key={tx.id}>
          <span>{tx.type}</span>
          <span>{tx.value} {tx.currency}</span>
          <span>{tx.status}</span>
          <span>{new Date(tx.timestamp).toLocaleDateString()}</span>
          <a href={tx.explorerUrl} target="_blank" rel="noopener noreferrer">
            View
          </a>
        </div>
      ))}

      {nextCursor && (
        <button
          onClick={() => loadPage(nextCursor)}
          disabled={loading}
        >
          {loading ? 'Loading...' : 'Load More'}
        </button>
      )}
    </div>
  );
}

Filtering by Type​

Fetch only specific transaction types.

import { useOneClient, CHAIN_IDS } from '@one_deploy/sdk';

function FilteredHistory() {
  const { engineClient } = useOneClient();

  const loadSendsOnly = async () => {
    const page = await engineClient.getWalletTransactions(
      '0x1234...abcd',
      { type: 'send' }
    );
    console.log('Sends:', page.transactions.length);
  };

  const loadSwapsAndBridges = async () => {
    const page = await engineClient.getWalletTransactions(
      '0x1234...abcd',
      { type: ['swap', 'bridge'] }
    );
    console.log('Swaps & bridges:', page.transactions.length);
  };

  const loadBaseTransactions = async () => {
    const page = await engineClient.getWalletTransactions(
      '0x1234...abcd',
      {
        chainId: CHAIN_IDS.BASE,
        status: 'confirmed',
        fromDate: '2025-01-01T00:00:00Z',
        limit: 50,
      }
    );
    console.log('Confirmed Base txs since 2025:', page.transactions.length);
  };

  return (
    <div>
      <button onClick={loadSendsOnly}>Sends Only</button>
      <button onClick={loadSwapsAndBridges}>Swaps & Bridges</button>
      <button onClick={loadBaseTransactions}>Base (2025+)</button>
    </div>
  );
}

getTransactionStatus​

Track the real-time status of a specific transaction by its ONE SDK transaction ID.

import { useOneClient } from '@one_deploy/sdk';

function TransactionTracker({ txId }: { txId: string }) {
  const { engineClient } = useOneClient();

  const checkStatus = async () => {
    const tx = await engineClient.getTransactionStatus(txId);

    console.log('Status:', tx.status);           // 'pending' | 'confirmed' | 'failed' | 'cancelled'
    console.log('Hash:', tx.transactionHash);
    console.log('Block:', tx.blockNumber);
    console.log('Explorer:', tx.explorerUrl);
  };

  return <button onClick={checkStatus}>Check Status</button>;
}

Method Signature​

getTransactionStatus(txId: string): Promise<Transaction>

Polling for Confirmation​

import { useOneClient } from '@one_deploy/sdk';

function useTransactionPolling() {
  const { engineClient } = useOneClient();

  const waitForConfirmation = async (
    txId: string,
    intervalMs: number = 3000,
    maxAttempts: number = 20
  ): Promise<Transaction> => {
    for (let i = 0; i < maxAttempts; i++) {
      const tx = await engineClient.getTransactionStatus(txId);

      if (tx.status === 'confirmed' || tx.status === 'failed') {
        return tx;
      }

      await new Promise((resolve) => setTimeout(resolve, intervalMs));
    }

    throw new Error(`Transaction ${txId} did not confirm within timeout`);
  };

  return { waitForConfirmation };
}

Next Steps​