TriportRPC
DashboardDocs

trace_filter

POSThttps://api.triport.io/

Returns all transaction traces (call frames) across a range of blocks that match an optional sender/recipient filter, with cursor-style pagination.

Ethereumeth_trace_filterpro (per-method RPS not listed in spec — governed by your pro-tier ceiling)

trace_filter scans a contiguous range of blocks and returns every trace (internal call, create, or suicide frame) whose sender and/or recipient match the supplied filter. Unlike trace_block — which is keyed to a single block — or trace_transaction — which is keyed to one transaction hash — trace_filter lets you sweep a window of history and narrow it down by address. It is the right tool for building an account's incoming/outgoing internal-transfer history or for indexing all activity that touched a particular contract.

Because a single block range can produce a very large number of traces, results are paginated with the after (offset) and count (limit) fields. Keep ranges modest and page through large result sets rather than requesting a huge window in one call.

This method requires the pro tier. Calls authenticated with a free-tier key are rejected with -32002 tier_insufficient.

Parameters

A single positional parameter: a filter object.

filterobjectrequired
Trace filter criteria (see fields below).
filter fieldsobject
fromBlockquantity | tagoptional
First block to scan, as a hex block number (e.g. "0x1312d00") or a tag ("earliest", "latest"). Defaults to "latest" if omitted.
toBlockquantity | tagoptional
Last block to scan (inclusive), hex number or tag. Defaults to "latest".
fromAddressarray of addressoptional
Only return traces sent from one of these addresses. Omit to match any sender.
toAddressarray of addressoptional
Only return traces sent to one of these addresses. Omit to match any recipient.
afterintegeroptional
Pagination offset — number of matching traces to skip before returning results. Defaults to 0.
countintegeroptional
Pagination limit — maximum number of traces to return. Omit to return all matches in the range.

Response

Response fields

result is an array of trace objects. Each object contains:

FieldTypeDescription
actionobjectDetails of the call frame: from, to, value, gas, input, and callType (call / delegatecall / staticcall). For create traces, init and creationMethod appear instead; for suicide, address, refundAddress, and balance.
resultobjectOutcome of the frame: gasUsed and output (or address + code for a create). Absent when error is present.
errorstringPresent instead of result when the frame reverted (e.g. "Reverted", "out of gas").
blockHashstringHash of the block containing the trace.
blockNumberintegerNumber of the block containing the trace.
subtracesintegerNumber of child traces directly under this frame.
traceAddressarray of integerPath of the frame within the call tree (empty for a top-level call).
transactionHashstringHash of the transaction that produced this trace.
transactionPositionintegerIndex of that transaction within its block.
typestringFrame type: call, create, or suicide.

Errors

CodeMeaningWhen it happens
-32002tier_insufficientYour API key's tier is below pro; upgrade to call trace_filter.
-32003rate_limitedYou exceeded your pro-tier request rate; retry after a short backoff.

These follow the standard Triport JSON-RPC error envelope — see the shared errors reference for the full response shape, HTTP status mapping, and retry guidance.

Examples

JavaScript (fetch)

const res = await fetch("https://api.triport.io/", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TRIPORT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "trace_filter",
    params: [{
      fromBlock: "0x1312d00",
      toBlock: "0x1312d10",
      toAddress: ["0x4f76e3b3cd2cf3a23e0c11a9f6f5f29c5e3f1f0a"],
      after: 0,
      count: 100,
    }],
  }),
});
const { result } = await res.json();
console.log(`${result.length} traces`);

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const client = new Triport({ apiKey: process.env.TRIPORT_API_KEY! });


const traces = await client.eth.traceFilter({
  fromBlock: "0x1312d00",
  toBlock: "0x1312d10",
  toAddress: ["0x4f76e3b3cd2cf3a23e0c11a9f6f5f29c5e3f1f0a"],
  after: 0,
  count: 100,
});


for (const t of traces) {
  console.log(t.transactionHash, t.action.value);
}

Python (triport-sdk)

import os
from triport import Triport


client = Triport(api_key=os.environ["TRIPORT_API_KEY"])


traces = client.eth.trace_filter({
    "fromBlock": "0x1312d00",
    "toBlock": "0x1312d10",
    "toAddress": ["0x4f76e3b3cd2cf3a23e0c11a9f6f5f29c5e3f1f0a"],
    "after": 0,
    "count": 100,
})


for t in traces:
    print(t["transactionHash"], t["action"]["value"])

Notes

  • Pagination. To page through a large result set, keep count fixed and advance after by count on each call (after: 0, then after: 100, …) until a page returns fewer than count traces. The result order is stable for a fixed block range.
  • Keep ranges small. A wide fromBlock/toBlock window with no address filter can match an enormous number of traces. Pair tight ranges with fromAddress / toAddress filters and pagination for predictable latency.
  • Address filters are OR-within / AND-across. Multiple entries in fromAddress match any of them; supplying both fromAddress and toAddress requires a trace to satisfy both sides.
  • Related methods: trace_block for a single block, trace_transaction for one transaction, and trace_call to trace a hypothetical call. All trace methods require the pro tier.