Transactions

Retrieve paginated transaction history for blockchain addresses with comprehensive filtering, full-text search, and detailed transaction data.

Cost: 1 credit per call

Index Limit — Addresses with more than 100,000 transactions are not automatically indexed. Contact support for assistance with large addresses.

Interactive Playground: Test this endpoint in the API Playground. Get your API key at data.octav.fi

Endpoint

GET https://api.octav.fi/v1/transactions

Required Parameters

addresses

string

required

Wallet address (EVM / SOL)

addresses=0x6426af179aabebe47666f345d69fd9079673f6cd

limit

integer

required

Number of transactions per page

Minimum: 1
Maximum: 250
Recommended: 10-50 for optimal performance

offset

integer

required

Pagination offset (0-based)

offset=0   # First page
offset=10  # Second page (if limit=10)
offset=20  # Third page (if limit=10)

Optional Parameters

Search & Filter

initialSearchText

string

Full-text search in transaction assets Searches across:

Token symbols
Token names
Contract addresses
Transaction descriptions

initialSearchText=USDC

interactingAddresses

string

Filter by interacting addresses (comma-separated) Shows only transactions where these addresses are involved:

interactingAddresses=0x123...,0x456...

networks

string

Filter by blockchain networks (comma-separated chain keys)

networks=ethereum,arbitrum,base

See Supported Blockchains for chain keys

txTypes

string

Filter by transaction types (comma-separated type keys)See Transaction TypesCommon types:

SEND - Token transfers out
RECEIVE - Token transfers in
SWAP - Token swaps
DEPOSIT - DeFi deposits
WITHDRAW - DeFi withdrawals
STAKE - Staking operations
CLAIM - Reward claims
APPROVE - Token approvals

txTypes=SWAP,DEPOSIT

protocols

string

Filter by protocol keys (comma-separated)See Protocol Keys

protocols=uniswap_v3,aave_v3

hideSpam

boolean

default:"false"

Exclude spam transactions

hideSpam=true

Sorting & Date Range

sort

string

default:"DESC"

Sort order by timestamp

DESC - Newest first (recommended)
ASC - Oldest first

sort=DESC

startDate

string

Start date in ISO 8601 format

startDate=2024-01-01T00:00:00Z

endDate

string

End date in ISO 8601 format

endDate=2024-12-31T23:59:59Z

NFT Filters

tokenId

string

Filter by NFT token ID

tokenId=1234

Response

Transaction Object

hash

string

Transaction hash

timestamp

string

Transaction timestamp in seconds since epoch

chain

object

Blockchain information

key: Chain identifier
name: Chain display name

from

string

Address initiating the transaction

string

Recipient address

type

string

Transaction type (DEPOSIT, WITHDRAWAL, SWAP, etc.)

protocol

object

Protocol information (if applicable)

key: Protocol identifier
name: Protocol display name

subProtocol

object

Sub-protocol information (if applicable)

key: Sub-protocol identifier
name: Sub-protocol name

value

string

Transaction value in native asset

valueFiat

string

Transaction value in USD

fees

string

Fees paid in native asset

feesFiat

string

Fees paid in USD

assetsIn

Asset[]

Assets received in the transaction

assetsOut

Asset[]

Assets sent out in the transaction

functionName

string

Smart contract function called

closedPnl

string

Realized profit/loss for the transaction (if available, otherwise “N/A”)

nativeAssetFees

object

Detailed fee breakdown

Example Request

curl -X GET "https://api.octav.fi/v1/transactions?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&limit=10&offset=0&sort=DESC&hideSpam=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

View Full Response

[
  {
    "hash": "0xa1b2c3d4e5f6...",
    "timestamp": "1699012800",
    "chain": {
      "key": "ethereum",
      "name": "Ethereum"
    },
    "from": "0x6426af179aabebe47666f345d69fd9079673f6cd",
    "to": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
    "type": "SWAP",
    "protocol": {
      "key": "uniswap_v3",
      "name": "Uniswap V3"
    },
    "value": "0",
    "valueFiat": "0",
    "fees": "0.002134",
    "feesFiat": "7.12",
    "assetsIn": [
      {
        "symbol": "WETH",
        "amount": "1.5",
        "value": "4800.00",
        "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
      }
    ],
    "assetsOut": [
      {
        "symbol": "USDC",
        "amount": "4795.23",
        "value": "4795.23",
        "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    ],
    "functionName": "swapExactTokensForTokens",
    "nativeAssetFees": {
      "symbol": "ETH",
      "amount": "0.002134",
      "value": "7.12"
    }
  },
  {
    "hash": "0xf9e8d7c6b5a4...",
    "timestamp": "1698926400",
    "chain": {
      "key": "arbitrum",
      "name": "Arbitrum"
    },
    "from": "0x6426af179aabebe47666f345d69fd9079673f6cd",
    "to": "0x794a61358D6845594F94dc1DB02A252b5b4814aD",
    "type": "DEPOSIT",
    "protocol": {
      "key": "aave_v3",
      "name": "Aave V3"
    },
    "value": "0",
    "valueFiat": "0",
    "fees": "0.000421",
    "feesFiat": "1.35",
    "assetsIn": [],
    "assetsOut": [
      {
        "symbol": "USDC",
        "amount": "10000",
        "value": "10000.00",
        "contractAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
      }
    ],
    "functionName": "supply",
    "nativeAssetFees": {
      "symbol": "ETH",
      "amount": "0.000421",
      "value": "1.35"
    }
  }
]

Use Cases

Transaction History
Filter by Type
Search Transactions
Date Range Query
Fee Analysis

Display transaction history with pagination:

async function getTransactionHistory(address, page = 1, pageSize = 20) {
  const offset = (page - 1) * pageSize;
  const params = new URLSearchParams({
    addresses: address,
    limit: pageSize.toString(),
    offset: offset.toString(),
    sort: 'DESC',
    hideSpam: 'true'
  });
  const response = await fetch(
    `https://api.octav.fi/v1/transactions?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  return await response.json();
}
// Get first page
const page1 = await getTransactionHistory(address, 1);
// Get next page
const page2 = await getTransactionHistory(address, 2);

Filter transactions by type:

async function getSwapTransactions(address) {
  const params = new URLSearchParams({
    addresses: address,
    txTypes: 'SWAP',
    limit: '50',
    offset: '0',
    sort: 'DESC'
  });
  const response = await fetch(
    `https://api.octav.fi/v1/transactions?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  const transactions = await response.json();
  // Calculate total swap volume
  const totalVolume = transactions.reduce((sum, tx) => {
    return sum + parseFloat(tx.valueFiat || 0);
  }, 0);
  console.log(`Total swap volume: $${totalVolume}`);
  return transactions;
}

Search for specific tokens or protocols:

async function searchTransactions(address, searchTerm) {
  const params = new URLSearchParams({
    addresses: address,
    initialSearchText: searchTerm,
    limit: '50',
    offset: '0',
    sort: 'DESC'
  });
  const response = await fetch(
    `https://api.octav.fi/v1/transactions?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  return await response.json();
}
// Search for USDC transactions
const usdcTxs = await searchTransactions(address, 'USDC');
// Search for Uniswap interactions
const uniswapTxs = await searchTransactions(address, 'Uniswap');

Query transactions within a date range:

async function getTransactionsInRange(address, startDate, endDate) {
  const params = new URLSearchParams({
    addresses: address,
    startDate: startDate.toISOString(),
    endDate: endDate.toISOString(),
    limit: '100',
    offset: '0',
    sort: 'DESC'
  });
  const response = await fetch(
    `https://api.octav.fi/v1/transactions?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  return await response.json();
}
// Get last 30 days
const endDate = new Date();
const startDate = new Date();
startDate.setDate(startDate.getDate() - 30);
const recentTxs = await getTransactionsInRange(
  address,
  startDate,
  endDate
);

Calculate total fees paid:

async function calculateTotalFees(address, startDate, endDate) {
  let offset = 0;
  const limit = 250;
  let totalFees = 0;
  let hasMore = true;
  while (hasMore) {
    const params = new URLSearchParams({
      addresses: address,
      startDate: startDate.toISOString(),
      endDate: endDate.toISOString(),
      limit: limit.toString(),
      offset: offset.toString(),
      sort: 'DESC'
    });
    const response = await fetch(
      `https://api.octav.fi/v1/transactions?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );
    const transactions = await response.json();
    if (transactions.length === 0) {
      hasMore = false;
    } else {
      transactions.forEach(tx => {
        totalFees += parseFloat(tx.feesFiat || 0);
      });
      offset += limit;
      hasMore = transactions.length === limit;
    }
  }
  return totalFees;
}
const fees = await calculateTotalFees(address, startDate, endDate);
console.log(`Total fees paid: $${fees.toFixed(2)}`);

Pagination Best Practices

Efficient Pagination

Use appropriate page sizes:

Small pages (10-20): Fast response, more requests
Medium pages (50-100): Balanced approach (recommended)
Large pages (200-250): Fewer requests, slower response

Track pagination state:

class TransactionPaginator {
  constructor(address, pageSize = 50) {
    this.address = address;
    this.pageSize = pageSize;
    this.currentOffset = 0;
  }

  async nextPage() {
    const params = new URLSearchParams({
      addresses: this.address,
      limit: this.pageSize.toString(),
      offset: this.currentOffset.toString(),
      sort: 'DESC'
    });

    const response = await fetch(
      `https://api.octav.fi/v1/transactions?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );

    const transactions = await response.json();

    if (transactions.length > 0) {
      this.currentOffset += transactions.length;
    }

    return {
      transactions,
      hasMore: transactions.length === this.pageSize
    };
  }
}

Handling Large Histories

For addresses with many transactions:

Use filters to reduce results:
- Filter by date range
- Filter by transaction type
- Filter by specific networks

Process in batches:

async function processAllTransactions(address, processor) {
  let offset = 0;
  const limit = 250;

  while (true) {
    const params = new URLSearchParams({
      addresses: address,
      limit: limit.toString(),
      offset: offset.toString(),
      sort: 'DESC'
    });

    const response = await fetch(
      `https://api.octav.fi/v1/transactions?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );

    const transactions = await response.json();

    if (transactions.length === 0) break;

    await processor(transactions);

    offset += transactions.length;

    if (transactions.length < limit) break;
  }
}

Implement caching:
- Cache transaction pages locally
- Only fetch new transactions since last sync
- Use startDate to fetch only recent data

Error Responses

400 Bad Request

Invalid parameters provided.

{
  "error": "Bad Request",
  "message": "limit must be between 1 and 250"
}

Common causes:

Missing required parameters (addresses, limit, offset)
Invalid parameter values
Invalid date format

404 Not Found

Address has more than 100,000 transactions.

{
  "error": "Address not indexed",
  "message": "This address has over 100,000 transactions and is not indexed"
}

Solution: Contact support for assistance with high-volume addresses

401 Unauthorized

Authentication failed.

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solution: Check your API key in the Authorization header

402 Payment Required

Insufficient credits.

{
  "error": "Insufficient credits",
  "message": "Please purchase more credits to continue"
}

Solution: Purchase more credits at data.octav.fi

Portfolio

View current portfolio holdings

Sync Transactions

Manually trigger transaction sync

Status

Check when transactions were last synced

Historical Portfolio

View portfolio at specific dates

Getting Started

Endpoints

Playground

AI Development

Reference

Endpoint

Required Parameters

Optional Parameters

Search & Filter

Sorting & Date Range

NFT Filters

Response

Transaction Object

Example Request

Example Response

Use Cases

Error Responses

Portfolio

Sync Transactions

Status

Historical Portfolio

Getting Started

Endpoints

Playground

AI Development

Reference

​Endpoint

​Required Parameters

​Optional Parameters

​Search & Filter

​Sorting & Date Range

​NFT Filters

​Response

​Transaction Object

​Example Request

​Example Response

​Use Cases

​Pagination Best Practices

​Error Responses

​Related Endpoints

Portfolio

Sync Transactions

Status

Historical Portfolio

Endpoint

Required Parameters

Optional Parameters

Search & Filter

Sorting & Date Range

NFT Filters

Response

Transaction Object

Example Request

Example Response

Use Cases

Pagination Best Practices

Error Responses

Related Endpoints