Skip to main content

​
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 executedCommon 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 pageRecommended: 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"
};

Build docs developers (and LLMs) love

Get started for freeTalk to us