> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces Support

> Fetch decoded EVM internal transactions (traces) for any wallet via the with-internal query param on the GoldRush Transactions API - no block-range scanning or client-side call-tree walking.

GoldRush exposes EVM transaction **traces**, which are the internal value transfers that occur during smart contract execution, through the Foundational API.

### What are internal transactions?

An EVM transaction is "external" when it originates from an externally-owned account (EOA) and is broadcast to the network. Once it begins executing, the contract it calls can in turn invoke other contracts and move native value between accounts. These nested value transfers are called **internal transactions** (or **internal transfers**, or **traces**).

Internal transactions are not stored as separate transactions on-chain. They only exist as side effects of the parent transaction's execution and can only be reconstructed by re-executing the transaction against an archive node. They are essential for accurately tracking:

* **Native token movement** triggered by contracts (e.g. a router contract forwarding ETH to a recipient).
* **DEX, lending, and bridge flows** where the EOA-visible `to_address` is a contract, not the ultimate recipient of funds.
* **Wallet balance reconciliation, accounting, and tax reporting** - without internal transactions, native-token balance deltas often cannot be explained from external transactions alone.
* **Failed sub-calls** within a multi-step transaction that still consumed gas.

### Enabling traces

Traces are opt-in via a query param on the Transactions API. Internal transfers cost `0.05` credits per item where supported:

* `with-internal` - includes internal transfers/transactions in the response.

When enabled, each transaction item in the response includes an `internal_transfers` array describing the `from_address`, `to_address`, `value` (in wei), and `gas_limit` of each internal transfer.

### API endpoints with trace support

* [Get a transaction](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-a-transaction.md)
* [Get earliest transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3.md)
* [Get recent transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3.md)
* [Get paginated transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3.md)

### Input data (`with-input-data`)

The same tracing pipeline also exposes a transaction's **input data** through a second query param, `with-input-data`. Like `with-internal`, it costs `0.05` credits per item where supported.

`with-input-data` is accepted on **two** endpoints, which is a smaller set than `with-internal`:

| Endpoint | `with-input-data` | Behaviour on an unsupported chain |
| - | - | - |
| [Get a transaction](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-a-transaction.md) | Supported | `501` naming the flag |
| [Get allchains transactions](https://goldrush.dev/docs/api-reference/foundational-api/cross-chain/get-allchains-transactions.md) | Supported | the transaction is returned without `input_data` |

> [!WARNING]
>
> The address-level, block-level and bulk transaction endpoints **ignore** `with-input-data`. They return `200` with no `input_data` field rather than an error, even on a chain that fully supports the feature, so a request that looks like it worked gives you nothing. Use one of the two endpoints above.

The two supported endpoints differ in how they decline. `transaction_v2` concerns one transaction on one chain, so it can fail loudly with a `501`. The allchains endpoint is explicitly multi-chain, so failing the whole request because one requested chain lacks the feature would be unhelpful; it returns every transaction and attaches `input_data` only to the ones whose chain can supply it. Check for the field per item rather than assuming the whole page has it.

#### What you get

When enabled, the transaction item gains an `input_data` object with exactly one field:

```bash theme={null}
curl -u "$GOLDRUSH_API_KEY:" \
  "https://api.covalenthq.com/v1/eth-mainnet/transaction_v2/0xa288cb7d0678ff85c9ba113dea85a1a6d249300d24c850cd78bea1f1e6376779/?with-input-data=true"
```

```json theme={null}
"input_data": {
  "method_id": "0xa9059cbb"
}
```

Without `with-input-data=true`, that same request returns the transaction with no `input_data` field at all.

`method_id` is the **4-byte function selector**: the first four bytes of the transaction's `input` field, which is the Keccak-256 hash of the function signature truncated to four bytes. It tells you *which* function the transaction called.

It is deliberately not the rest of the calldata and not the decoded arguments. If you need the argument values, you still have to fetch the raw `input` yourself and decode it against the contract ABI. A plain native-token transfer has empty calldata and therefore no method ID.

#### What it is useful for

* **Labelling a transaction's intent** without an ABI lookup. `0xa9059cbb` is an ERC-20 `transfer`, `0x095ea7b3` is an `approve`. A selector is enough to bucket transactions by action.
* **Filtering before you decode.** Selectors are cheap to compare, so you can discard the transactions you do not care about before paying for ABI resolution.
* **Telling apart calls to the same contract.** Two transactions to one router address look identical until you can see that one is a swap and the other is a liquidity withdrawal.

> [!NOTE]
>
> A selector is a truncated hash, so it is not unique. `0xa9059cbb` is ERC-20 `transfer(address,uint256)`, but five other published signatures hash to the same four bytes; `0x095ea7b3` is `approve(address,uint256)` plus three others. In practice the contract you are calling disambiguates it, but do not treat a selector as proof of intent on its own.

#### Which chains serve it

[`GET /v1/chains/`](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-all-chains) returns `is_input_data_supported` for every chain, and that flag is the predicate the endpoints gate on. Where it is `true` the chain serves the param. Where it is `false` the request returns `501 This chain does not currently support flag: with-input-data.` Probed against the live gate on all 43 chains on 2026-10-15, the flag and the gate agreed on every one.

> [!TIP]
>
> Read the flag at runtime instead of hard-coding a chain list. Coverage widens as chains are onboarded, so a list written into your code goes stale.

To check a single chain by hand, call [Get a transaction](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-a-transaction.md) with `with-input-data=true`. The capability gate runs before the transaction hash is validated, so you do not need a real hash to probe it: a `501` naming the flag means the chain does not serve it, and anything else means it does.

`is_input_data_supported` and `is_internal_tx_supported` are independent of each other rather than a ladder, and a chain can carry either one without the other. There is also `is_historical_balances_supported`, which follows neither: `btc-mainnet` supports historical balances and neither tracing feature.

### `with-internal` vs. raw `trace_*` / `debug_*` (JSON-RPC)

A common point of confusion is how the Foundational API's `with-internal` param relates to the raw [`trace_*` and `debug_*` JSON-RPC methods](https://goldrush.dev/docs/goldrush-json-rpc/debug-trace). They solve different problems.

`with-internal` is built for **wallet-level internal transaction history**: ask for one address and get back its internal transfers, already decoded and attached to each transaction, across the supported chains. The raw `trace_*` / `debug_*` methods are low-level **per-transaction or per-block primitives** - powerful, but they do not answer "show me this wallet's internal transfers" without significant client-side work.

#### Why raw RPC is impractical for wallet history

Reconstructing a single wallet's internal-transfer history from raw traces is expensive and chain-dependent:

* **`trace_filter` (Ethereum / Erigon-style nodes)** returns matching internal calls directly, but a wallet can be either the sender *or* the recipient, so you must scan the block range **twice** - once with `fromAddress` and once with `toAddress`. Even chunking at 1M blocks per request, a full-history scan is roughly **50 calls per direction** (\~100 total) on Ethereum alone.
* **`trace_filter` is unsupported on OP-stack L2s** (and many other chains) unless you run the node yourself or your RPC vendor has explicitly enabled it. The fallback is `debug_traceBlockByNumber`, which forces you to **fetch and trace every block** in the range and then filter client-side for calls whose `from` or `to` matches the wallet - far more calls and far more data to walk.
* In both cases you still have to **walk the resulting call tree yourself** and decode raw payloads to make the data usable.

#### The honest trade-off

For a **single transaction on `eth-mainnet`**, calling `trace_transaction` (or `debug_traceTransaction`) directly over raw RPC is cheaper than the Foundational API. What `with-internal` adds is:

* A **decoded payload** rather than raw call frames.
* **No client-side call-tree walking** - internal transfers arrive flattened and attached to each transaction.
* **Uniform behavior across chains**, including chains where `trace_filter` is unavailable.

This is the same trade-off as fetching the balance of a single token: you *can* compose it from raw `eth_call`s, but for anything beyond one-off lookups the enriched, multi-chain endpoint is what saves you the integration work.

#### When to use which

| You want... | Use |
| - | - |
| A wallet's full internal-transfer history, decoded | Foundational API `with-internal` |
| Internal transfers attached to a known transaction, decoded | Foundational API `with-internal` on [Get a transaction](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-a-transaction.md) |
| Opcode-level / Parity-style trace of one known tx on Ethereum | [`trace_transaction` / `debug_traceTransaction`](https://goldrush.dev/docs/goldrush-json-rpc/debug-trace) |
| Custom tracer output (`callTracer`, `prestateTracer`, state diff) | [`debug_*` / `trace_*` JSON-RPC](https://goldrush.dev/docs/goldrush-json-rpc/debug-trace) |

### Supported chains

Tracing is currently available on the following chains:

* [ApeChain](https://goldrush.dev/docs/chains/apechain.md)
* [Arbitrum](https://goldrush.dev/docs/chains/arbitrum.md)
* [Arc](https://goldrush.dev/docs/chains/arc.md)
* [Avalanche C-Chain](https://goldrush.dev/docs/chains/avalanche-c-chain.md)
* [Base](https://goldrush.dev/docs/chains/base.md)
* [Berachain](https://goldrush.dev/docs/chains/berachain.md)
* [BNB Smart Chain (BSC)](https://goldrush.dev/docs/chains/bnb-smart-chain-bsc.md)
* [Ethereum](https://goldrush.dev/docs/chains/ethereum.md)
* [Gnosis](https://goldrush.dev/docs/chains/gnosis.md)
* [Linea](https://goldrush.dev/docs/chains/linea.md)
* [Mantle](https://goldrush.dev/docs/chains/mantle.md)
* [MegaETH](https://goldrush.dev/docs/chains/megaeth.md)
* [Optimism](https://goldrush.dev/docs/chains/optimism.md)
* [Plasma](https://goldrush.dev/docs/chains/plasma.md)
* [Polygon](https://goldrush.dev/docs/chains/polygon.md)
* [Robinhood Chain](https://goldrush.dev/docs/chains/robinhood-chain.md)
* [Taiko](https://goldrush.dev/docs/chains/taiko.md)
* [Unichain](https://goldrush.dev/docs/chains/unichain.md)
* [World Chain](https://goldrush.dev/docs/chains/world-chain.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.