Trace API

Trace API Quickstart

The Trace API provides insights into transaction processing and on-chain activity.

To use the Trace API your Alchemy plan must be set to the Growth or Enterprise tiers. Upgrade your plan for access.

Don’t have an API key?

Sign up or upgrade your plan for access. Get started for free

Introduction

The Trace API methods provide full externality trace functions on transactions executed in the Ethereum chain. Filtering is simple by using just the address information. The returned information includes the execution of the following:

  • CREATE
  • SUICIDE
  • Variants of the CALL
  • Input data
  • Output data
  • Gas usage
  • Amount transferred
  • Success status of individual actions

Trace use cases

Common use cases for the Trace API come in all flavors. Below are popular ones:

Use caseDescriptionEndpoint
Trace callExecutes the given call and returns a number of possible traces for it.trace_call
Trace blockReturns the traces executed in the block.trace_block
Trace getReturns the traces for a transaction by its hash.trace_get

Trace types

TypeParameterDescriptionNetwork Support
Transaction TracetraceTrace of your transaction. See trace actions for details.Ethereum Mainnet & Goerli
State differencestateDiffEthereum state changed values of a transaction.Ethereum Mainnet & Goerli
Virtual Machine Execution TracevmTraceRuns a full trace of the VM’s state & subcalls in the transaction.None

Trace actions types

CREATE

  • Used to create a smart contract.

Example response

json
1{
2    "action": {
3      "from": "0x6090a6e47849629b7245dfa1ca21d94cd15878ef",
4      "gas": "0x6a7f1",
5      "init": "0x606060405260405160208061051683398101604052515b60028054600160a060020a03808416600160a060020a0319928316179092556000805433909316929091169190911790554260019081556005805460ff19169091179055346004555b505b6104a6806100706000396000f300606060405236156100885763ffffffff60e060020a60003504166305b34410811461008a5780630b5ab3d5146100ac57806313af4035146100be5780632b20e397146100dc5780633fa4f24514610108578063674f220f1461012a5780638da5cb5b14610156578063b0c8097214610182578063bbe427711461019c578063faab9d39146101b1575bfe5b341561009257fe5b61009a6101cf565b60408051918252519081900360200190f35b34156100b457fe5b6100bc6101d5565b005b34156100c657fe5b6100bc600160a060020a036004351661021d565b005b34156100e457fe5b6100ec6102c3565b60408051600160a060020a039092168252519081900360200190f35b341561011057fe5b61009a6102d2565b60408051918252519081900360200190f35b341561013257fe5b6100ec6102d8565b60408051600160a060020a039092168252519081900360200190f35b341561015e57fe5b6100ec6102e7565b60408051600160a060020a039092168252519081900360200190f35b341561018a57fe5b6100bc60043560243515156102f6565b005b34156101a457fe5b6100bc600435610382565b005b34156101b957fe5b6100bc600160a060020a0360043516610431565b005b60015481565b60055460ff16156101e65760006000fd5b600254604051600160a060020a039182169130163180156108fc02916000818181858888f193505050501561021a5761deadff5b5b565b60005433600160a060020a039081169116146102395760006000fd5b600160a060020a038116151561024f5760006000fd5b600280546003805473ffffffffffffffffffffffffffffffffffffffff19908116600160a060020a03808516919091179092559084169116811790915560408051918252517fa2ea9883a321a3e97b8266c2b078bfeec6d50c711ed71f874a90d500ae2eaf369181900360200190a15b5b50565b600054600160a060020a031681565b60045481565b600354600160a060020a031681565b600254600160a060020a031681565b60005433600160a060020a039081169116146103125760006000fd5b60055460ff1615156103245760006000fd5b8160045410156103345760006000fd5b6004829055600254604051600160a060020a039182169130163184900380156108fc02916000818181858888f193505050501580156103705750805b1561037b5760006000fd5b5b5b5b5050565b60005433600160a060020a0390811691161461039e5760006000fd5b60055460ff1615156103b05760006000fd5b6005805460ff1916905561dead6108fc6103e883810330600160a060020a031631025b604051919004801590920291906000818181858888f1935050505015156103fa5760006000fd5b6040517fbb2ce2f51803bba16bc85282b47deeea9a5c6223eabea1077be696b3f265cf1390600090a16102bf6101d5565b5b5b5b50565b60005433600160a060020a0390811691161461044d5760006000fd5b6000805473ffffffffffffffffffffffffffffffffffffffff1916600160a060020a0383161790555b5b505600a165627a7a72305820fbfa6f8a2024760ef0e0eb29a332c9a820526e92f8b4fbcce6f00c7643234b140029000000000000000000000000a7f3659c53820346176f7e0e350780df304db179",
6      "value": "0xe4b4b8af6a70000"
7    },
8    "blockHash": "0x6d00f7707938cca36b0730d8f7f090543242002b6fa0fe94bf85b9ab02e6bed6",
9    "blockNumber": 4000036,
10    "result": {
11      "address": "0xfc9779d9a0f2715435a3e8ebf780322145d7546e",
12      "code": "0x606060405236156100885763ffffffff60e060020a60003504166305b34410811461008a5780630b5ab3d5146100ac57806313af4035146100be5780632b20e397146100dc5780633fa4f24514610108578063674f220f1461012a5780638da5cb5b14610156578063b0c8097214610182578063bbe427711461019c578063faab9d39146101b1575bfe5b341561009257fe5b61009a6101cf565b60408051918252519081900360200190f35b34156100b457fe5b6100bc6101d5565b005b34156100c657fe5b6100bc600160a060020a036004351661021d565b005b34156100e457fe5b6100ec6102c3565b60408051600160a060020a039092168252519081900360200190f35b341561011057fe5b61009a6102d2565b60408051918252519081900360200190f35b341561013257fe5b6100ec6102d8565b60408051600160a060020a039092168252519081900360200190f35b341561015e57fe5b6100ec6102e7565b60408051600160a060020a039092168252519081900360200190f35b341561018a57fe5b6100bc60043560243515156102f6565b005b34156101a457fe5b6100bc600435610382565b005b34156101b957fe5b6100bc600160a060020a0360043516610431565b005b60015481565b60055460ff16156101e65760006000fd5b600254604051600160a060020a039182169130163180156108fc02916000818181858888f193505050501561021a5761deadff5b5b565b60005433600160a060020a039081169116146102395760006000fd5b600160a060020a038116151561024f5760006000fd5b600280546003805473ffffffffffffffffffffffffffffffffffffffff19908116600160a060020a03808516919091179092559084169116811790915560408051918252517fa2ea9883a321a3e97b8266c2b078bfeec6d50c711ed71f874a90d500ae2eaf369181900360200190a15b5b50565b600054600160a060020a031681565b60045481565b600354600160a060020a031681565b600254600160a060020a031681565b60005433600160a060020a039081169116146103125760006000fd5b60055460ff1615156103245760006000fd5b8160045410156103345760006000fd5b6004829055600254604051600160a060020a039182169130163184900380156108fc02916000818181858888f193505050501580156103705750805b1561037b5760006000fd5b5b5b5b5050565b60005433600160a060020a0390811691161461039e5760006000fd5b60055460ff1615156103b05760006000fd5b6005805460ff1916905561dead6108fc6103e883810330600160a060020a031631025b604051919004801590920291906000818181858888f1935050505015156103fa5760006000fd5b6040517fbb2ce2f51803bba16bc85282b47deeea9a5c6223eabea1077be696b3f265cf1390600090a16102bf6101d5565b5b5b5b50565b60005433600160a060020a0390811691161461044d5760006000fd5b6000805473ffffffffffffffffffffffffffffffffffffffff1916600160a060020a0383161790555b5b505600a165627a7a72305820fbfa6f8a2024760ef0e0eb29a332c9a820526e92f8b4fbcce6f00c7643234b140029",
13      "gasUsed": "0x52ce0"
14    },
15    "subtraces": 0,
16    "traceAddress": [
17      0
18    ],
19    "transactionHash": "0xc9601ea5ca42e57c3ef1d770ab0b278d6aadf2511a4feb879cba573854443423",
20    "transactionPosition": 70,
21    "type": "create"
22  },

Create parameter definitions

ParameterDescriptionExample
fromThe address that created the contract.0x6090a6e47849629b7245dfa1ca21d94cd15878ef
gasContract gas fee to create the contract.0x6a7f1
initInitialization code to create the contract.0x6060604052604051602080610516833981016040...
valueThe value sent to the contract.0xe4b4b8af6a7000
blockHashBlock hash ID in the transaction.0x6d00f7707938cca36b0730d8f7f090543242002b6fa0fe94bf85b9ab02e6bed6
blockNumberTransaction block number.4000036
addressLocation address of the new contract.0xfc9779d9a0f2715435a3e8ebf780322145d7546e
codeThe contract code.0x606060405236156100885763ffffffff60e060020...
gasUsedRequired fee (gas) to create the contract.0x52ce0
subtracesTotal number of transaction child traces.0
traceAddressIndex of a trace & order of subcalls.0
transactionHashHash ID of the transaction.0xc9601ea5ca42e57c3ef1d770ab0b278d6aadf2511a4feb879cba573854443423
transactionPositionThe transaction position in the block.70
typeType of operation code (OPCODE).create

SUICIDE

  • SUICIDE is captured when a smart contract is destroyed. That is when the selfdestruct function of Solidity is used.
  • SUICIDE transfers the contract’s balance to the address specified in the selfdestruct function clearing on-chain memory.
  • The cleared memory is processed as a refund of the total gas cost to complete the transaction.

Example response

json
1{
2    "action": {
3      "address": "0x87051f6ba0562fdb0485763562bf34cb2ad705b1",
4      "refundAddress": "0x000000000000000000000000000000000000dead",
5      "balance": "0x0"
6    },
7    "blockHash": "0x6d00f7707938cca36b0730d8f7f090543242002b6fa0fe94bf85b9ab02e6bed6",
8    "blockNumber": 4000036,
9    "result": null,
10    "subtraces": 0,
11    "traceAddress": [
12      1,
13      2,
14      2
15    ],
16    "transactionHash": "0xbc15addb97490a168dc1d099ab8537caf2e4ff7d1deeff6d685d2d594a750037",
17    "transactionPosition": 45,
18    "type": "suicide"
19  },

SUICIDE parameter definitions

ParameterDescriptionExample
addressThe address of contract to destroy.0x87051f6ba0562fdb0485763562bf34cb2ad705b1
refundAddressAddress to send remainder of contract balance.0x000000000000000000000000000000000000dead
blockHashBlock hash ID of the transaction.0x6d00f7707938cca36b0730d8f7f090543242002b6fa0fe94bf85b9ab02e6bed6
blockNumberTransaction block number.4000036
resultUsed for SELFDESTRUCT calls.null
subtracesTotal number of transaction child traces.0
traceAddressIndex of the trace & the order of subcalls.1 and 2
transactionHashHash ID of the transaction.0xbc15addb97490a168dc1d099ab8537caf2e4ff7d1deeff6d685d2d594a750037
transactionPositionThe position of the transaction in the block.45
typeType of operation code (OPCODE).suicide

CALL

Example response

json
1{
2    "action": {
3      "from": "0xbc9f06dd67578b0b8b4d87fda9acde453bc4c067",
4      "callType": "call",
5      "gas": "0x97478",
6      "input": "0xfebefd610000000000000000000000000000000000000000000000000000000000000040cc849afc28894f79411f12309e75c71ded27d1666b75a2423633c204e671cb1e00000000000000000000000000000000000000000000000000000000000000036eaec0ff7c4899bec2db1479d7d195d614ca26819a301523d82daaaaf436122d2ceb36dfa12b359202b4dfd756478988f5023bf7297afa81f563d4b6242e36e707671a8bf38ee483a37feca948997dcfba17b3372e166ba5c824629beeed6b5c",
7      "to": "0x6090a6e47849629b7245dfa1ca21d94cd15878ef",
8      "value": "0x2386f26fc10000"
9    },
10    "blockHash": "0x6d00f7707938cca36b0730d8f7f090543242002b6fa0fe94bf85b9ab02e6bed6",
11    "blockNumber": 4000036,
12    "result": {
13      "gasUsed": "0x7ad71",
14      "output": "0x"
15    },
16    "subtraces": 4,
17    "traceAddress": [],
18    "transactionHash": "0x552b31a3a9c92577d65db62cf9f729e81571e10cad90e356423adcfa2caebacc",
19    "transactionPosition": 71,
20    "type": "call"
21  }

CALL parameter definitions

ParameterDescriptionExample
fromAddress of the sender.0xbc9f06dd67578b0b8b4d87fda9acde453bc4c067
callTypeThe type of CALL.call,delegatecall,callcode or staticcall
gasThe gas included in the transaction.0x97478
inputSpecific call function on the contract.0xfebefd61000000000000000000000000000000000000000...
toAddress of the receiver.0x6090a6e47849629b7245dfa1ca21d94cd15878ef
valueTransferred value amount.0x2386f26fc10000
blockHashTransaction block hash ID.0x6d00f7707938cca36b0730d8f7f090543242002b6fa0fe94bf85b9ab02e6bed6
blockNumberTransaction block number.4000036
gasUsedgas used to execute the transaction.0x7ad71
outputThe result of the smart contract function call.0x
subtracesTotal number of transaction child traces.4
traceAddressIndex of a trace & the order of subcalls.[]
transactionHashHash ID of the transaction.0x552b31a3a9c92577d65db62cf9f729e81571e10cad90e356423adcfa2caebacc
transactionPositionThe position of the transaction in the block.71
typeType of operation code (OPCODE).call

How to read a traceAddress

Traces are structured in a tree format. The traceAddress field represents the position of the trace in the tree. Below is a diagram of the traceAddress set of tree results:

768

Trace tree diagram

Helpful Resources