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
Comma-separated list of wallet addresses
addresses=0x6426af179aabebe47666f345d69fd9079673f6cd
Multiple addresses:
addresses=0x123...,0x456...
​
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
​
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
​
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

[
  {
    "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);

​
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