Skip to main content
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
hideDust
boolean
default:"false"
Exclude dust transactions
hideDust=true

Sorting & Date Range

sort
string
default:"DESC"
Sort order by timestamp
  • DESC - Newest first (recommended)
  • ASC - Oldest first
sort=DESC
startDate
string
Start of the date range, ISO 8601. Inclusive — filters timestamp >= startDate at the exact instant you pass, compared in UTC.Use camelCase; start_date is rejected with a 400 validation error. Omit to start from the wallet’s first indexed transaction.
startDate=2024-01-01T00:00:00Z
endDate
string
End of the date range, ISO 8601. Inclusive, but rounded up to the end of that UTC calendar day (23:59:59Z) — the time-of-day you send is ignored. Filters timestamp <= endOfDay(endDate).Use camelCase; end_date is rejected with a 400 validation error. Omit to include transactions up to the present.
endDate=2024-12-31T23:59:59Z
Building daily windows without duplicates — because endDate rounds up to the end of its UTC calendar day:
  • Single day: set startDate and endDate to the same date (e.g. startDate=2026-05-27&endDate=2026-05-27 returns 2026-05-27 00:00:00Z23:59:59Z).
  • Range: set startDate to the first day and endDate to the last day you want included.
  • Do not set endDate to the next day’s midnight (e.g. 2026-05-28T00:00:00Z) — it rounds up to the end of the 28th and pulls in an extra day, so the same transaction appears in two consecutive windows.
Since timestamp is integer epoch seconds, contiguous same-day windows have no overlap and no gap.

NFT Filters

tokenId
string
Filter by NFT token ID
tokenId=1234

Response

The response is an object with a single transactions key holding the array:
{ "transactions": [ { /* ...tx... */ } ] }

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
to
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.Each asset contains symbol, name, balance, value, decimal, contract, chainKey, and chainContract. The token quantity is balance (not amount), and the on-chain address is contract (not contractAddress); native assets use the zero address. There is no nested chain object at the asset level — use chainKey / chainContract.
assetsOut
Asset[]
Assets sent out in the transaction. Same shape as assetsIn.
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

{
  "transactions": [
    {
      "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",
          "name": "wrapped ether",
          "balance": "1.5",
          "value": "4800.00",
          "decimal": "18",
          "contract": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "chainKey": "ethereum",
          "chainContract": "ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
        }
      ],
      "assetsOut": [
        {
          "symbol": "usdc",
          "name": "usd coin",
          "balance": "4795.23",
          "value": "4795.23",
          "decimal": "6",
          "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "chainKey": "ethereum",
          "chainContract": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        }
      ],
      "functionName": "swapExactTokensForTokens",
      "nativeAssetFees": {
        "symbol": "eth",
        "balance": "0.002134",
        "value": "7.12",
        "contract": "0x0000000000000000000000000000000000000000",
        "chainKey": "ethereum"
      }
    },
    {
      "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",
          "name": "usd coin",
          "balance": "10000",
          "value": "10000.00",
          "decimal": "6",
          "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
          "chainKey": "arbitrum",
          "chainContract": "arbitrum:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
        }
      ],
      "functionName": "supply",
      "nativeAssetFees": {
        "symbol": "eth",
        "balance": "0.000421",
        "value": "1.35",
        "contract": "0x0000000000000000000000000000000000000000",
        "chainKey": "arbitrum"
      }
    }
  ]
}

Use Cases

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}`
      }
    }
  );
  const { transactions } = await response.json();
  return transactions;
}
// Get first page
const page1 = await getTransactionHistory(address, 1);
// Get next page
const page2 = await getTransactionHistory(address, 2);

Pagination Best Practices

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
    };
  }
}
For addresses with many transactions:
  1. Use filters to reduce results:
    • Filter by date range
    • Filter by transaction type
    • Filter by specific networks
  2. 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;
      }
    }
    
  3. Implement caching:
    • Cache transaction pages locally
    • Only fetch new transactions since last sync
    • Use startDate to fetch only recent data

Error Responses

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
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
Authentication failed.
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
Solution: Check your API key in the Authorization header
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