Transaction Types

Type definitions for transaction tracking and history in OneBalance

Overview

The Transaction types define the structure for tracking swap and transfer operations, including their status, chain operations, and historical data.

Transaction

Represents a complete transaction record for a swap or transfer operation.

export interface Transaction {
  quoteId: string;
  status: TransactionStatus;
  user: string;
  recipientAccountId?: string;
  originChainOperations: ChainOperation[];
  destinationChainOperations?: ChainOperation[];
  type: 'SWAP' | 'TRANSFER';
  originToken: TokenInfo;
  destinationToken?: TokenInfo;
  timestamp: string;
}

Properties

quoteId · string · required

Unique identifier for the quote that generated this transaction

status · TransactionStatus · required

Current status of the transaction. See TransactionStatus below.

user · string · required

The user address who initiated the transaction

recipientAccountId · string

Optional recipient account identifier (CAIP format) for transfer operations

originChainOperations · ChainOperation[] · required

Array of operations executed on origin chains. See ChainOperation below.

destinationChainOperations · ChainOperation[]

Optional array of operations executed on destination chain. See ChainOperation below.

type · 'SWAP' | 'TRANSFER' · required

Type of transaction:

• SWAP: Token swap operation
• TRANSFER: Token transfer to another account

originToken · TokenInfo · required

Information about the source token. See TokenInfo below.

destinationToken · TokenInfo

Optional information about the destination token (required for swaps). See TokenInfo below.

timestamp · string · required

ISO 8601 timestamp when the transaction was created

Example

const transaction: Transaction = {
  quoteId: "quote_123abc",
  status: "COMPLETED",
  user: "0x1234567890abcdef",
  recipientAccountId: "eip155:137:0x9876543210fedcba",
  originChainOperations: [
    {
      hash: "0xabcd1234...",
      chainId: 1,
      explorerUrl: "https://etherscan.io/tx/0xabcd1234..."
    }
  ],
  destinationChainOperations: [
    {
      hash: "0xef567890...",
      chainId: 137,
      explorerUrl: "https://polygonscan.com/tx/0xef567890..."
    }
  ],
  type: "SWAP",
  originToken: {
    aggregatedAssetId: "ob:usdc",
    amount: "1000000000",
    assetType: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    fiatValue: "1000.00"
  },
  destinationToken: {
    aggregatedAssetId: "ob:eth",
    amount: "285714285714285714",
    assetType: "eip155:137/slip44:60",
    fiatValue: "1000.00"
  },
  timestamp: "2026-03-04T10:30:00Z"
};

---

TransactionStatus

Enum type representing the possible states of a transaction.

export type TransactionStatus = 'PENDING' | 'COMPLETED' | 'FAILED' | 'REFUNDED';

Values

PENDING · string

Transaction has been created but execution has not completed

COMPLETED · string

Transaction has been successfully executed on all required chains

FAILED · string

Transaction execution failed

REFUNDED · string

Failed transaction has been refunded to the user

---

ChainOperation

Information about an operation executed on a specific blockchain.

export interface ChainOperation {
  hash: string;
  chainId: number;
  explorerUrl: string;
}

Properties

hash · string · required

Transaction hash on the blockchain

chainId · number · required

Numeric chain identifier where the transaction was executed

Common chain IDs:

• 1: Ethereum Mainnet
• 10: Optimism
• 137: Polygon
• 8453: Base
• 42161: Arbitrum
• 43114: Avalanche

explorerUrl · string · required

Full URL to view the transaction on a block explorer

Example

const operation: ChainOperation = {
  hash: "0x1234567890abcdef...",
  chainId: 1,
  explorerUrl: "https://etherscan.io/tx/0x1234567890abcdef..."
};

---

TokenInfo

Extended token information including fiat value calculations.

export interface TokenInfo {
  aggregatedAssetId: string;
  amount: string;
  assetType: string | string[];
  fiatValue?: string | { assetType: string; fiatValue: string }[];
  minimumAmount?: string;
  minimumFiatValue?: string;
}

Properties

aggregatedAssetId · string · required

The OneBalance aggregated asset identifier (e.g., ob:eth, ob:usdc, ob:dai)

amount · string · required

Token amount as a string (represents BigInt with token’s decimals)

Example: "1000000" for 1 USDC (6 decimals)

assetType · string | string[] · required

CAIP-19 format asset identifier(s)

• Single string: Asset on one chain
• Array of strings: Aggregated asset across multiple chains

Format: {namespace}:{chainId}/{assetNamespace}:{assetReference}

Examples:

• "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" (USDC on Ethereum)
• "eip155:137/slip44:60" (ETH on Polygon)

fiatValue · string | array

Fiat value of the token amount

• String: Total fiat value (e.g., "1000.00")
• Array: Per-chain breakdown for aggregated assets
  • Each object contains assetType and fiatValue

minimumAmount · string

Minimum amount required for the operation (as string)

minimumFiatValue · string

Minimum fiat value required for the operation

Example - Simple Token

const simpleToken: TokenInfo = {
  aggregatedAssetId: "ob:usdc",
  amount: "1000000000", // 1000 USDC
  assetType: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  fiatValue: "1000.00"
};

Example - Aggregated Token

const aggregatedToken: TokenInfo = {
  aggregatedAssetId: "ob:usdc",
  amount: "2000000000", // 2000 USDC total
  assetType: [
    "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174"
  ],
  fiatValue: [
    {
      assetType: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      fiatValue: "1200.00"
    },
    {
      assetType: "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      fiatValue: "800.00"
    }
  ],
  minimumAmount: "100000", // 0.1 USDC
  minimumFiatValue: "0.10"
};

---

TransactionHistoryResponse

Response structure for transaction history queries with pagination support.

export interface TransactionHistoryResponse {
  transactions: Transaction[];
  continuation?: string;
}

Properties

transactions · Transaction[] · required

Array of transaction records. See Transaction above.

continuation · string

Pagination token to fetch the next page of results. If not present, there are no more results.

Example

const history: TransactionHistoryResponse = {
  transactions: [
    {
      quoteId: "quote_123",
      status: "COMPLETED",
      user: "0x1234...",
      type: "SWAP",
      originToken: { /* ... */ },
      destinationToken: { /* ... */ },
      originChainOperations: [{ /* ... */ }],
      timestamp: "2026-03-04T10:30:00Z"
    },
    // ... more transactions
  ],
  continuation: "eyJwYWdlIjoyLCJsaW1pdCI6MTB9" // Base64 encoded pagination token
};

---

TransactionHistoryParams

Parameters for querying transaction history.

export interface TransactionHistoryParams {
  user: string;
  limit: number;
  continuation?: string;
}

Properties

user · string · required

User address to query transactions for

limit · number · required

Maximum number of transactions to return per page

Recommended: 10-50 transactions per page

continuation · string

Pagination token from a previous response to fetch the next page

Example

const params: TransactionHistoryParams = {
  user: "0x1234567890abcdef",
  limit: 20,
  continuation: "eyJwYWdlIjoyLCJsaW1pdCI6MjB9"
};