Transfers API (Tx History)

The Transfers API allows you to easily fetch historical transactions for any address without having to scan the entire chain and index everything for each of your users.

Transfers are a representation of value being exchanged between two accounts. Often times users wish to see the historical transactions associated with a specific account or address. This is currently an extremely challenging and inefficient task, requiring users to scan the entire blockchain and index everything to search for transactions associated with the desired address. However, with the Transfers API users can query all types of historical transactions for a given address in a single request.
If you don't have an account yet, you can sign up with Alchemy for free. 
TIP: Check out this tutorial on integrating historical transaction data into your dApp to learn how to get started using the Transfers API!
Types of Transfers
There are five main types of transfers that are captured when using this API.
1. External Eth Transfers
These are top level ethereum transactions that occur with a from address being an external (user created) address. External addresses have private keys and are accessed by users.
2. ERC20 Transfers
Event logs for ERC20 transfers.
NOTE: ERC20 Transfers are also included in the "token" category
3. ERC721 Transfers
Event logs for ERC721 transfers.
NOTE: ERC721 Transfers are also included in the "token" category
4. ERC1155 Transfers
These are event logs for ERC1155 transfers.
5. Internal Eth Transfers
These are transfers that occur where the fromAddress is an internal (smart contract) address. (ex: a smart contract calling another smart contract or smart contract calling another external address).
NOTE: For efficiency, we do not return internal transfers with 0 value as they don't provide useful information without digging deeper into the internal transaction itself. If you are interested in these type of events see our Trace API.
Additionally, we do not include any internal transfers with call typedelegatecall because although they have a _value _associated with them they do not actually transfer that value (see Appendix H of the Ethereum Yellow Paper if you're curious). We also do not include miner rewards as an internal transfer.
alchemy_getAssetTransfers
NOTE:alchemy_getAssetTransfers is currently only available on Mainnet.
Parameters
Parameters:
Object - An object with the following fields (required):
fromBlock: inclusive from block (hex string or latest). optional (defaults tolatest)
toBlock: inclusive to block (hex string or latest). optional (defaults to latest)
fromAddress: from address (hex string). optional (default wildcard - any address)
toAddress: to address (hex string). optional (default wildcard - any address)
contractAddresses: list of contract addresses (hex strings) for token transfers. optional (default wildcard - any address)
category: Optional array of categories, can be any of the following: "external", "internal", "token", "erc20", "erc721", "erc1155" (defaults to the following categories: ["external", "internal", "token"])
excludeZeroValue: aBoolean to exclude transfers with zero value. optional (default true)
maxCount: max hex string number of results to return per call. optional (default and max1000 or 0x3e8)
pageKey: uuid for pagination. optional. If more results are available, a uuid pageKey will be returned in the response. Pass that uuid into pageKey to fetch the next 1000 or maxCount.
NOTE: fromAddress and toAddress are ANDed together when filtering.
NOTE: contractAddresses are OR ed together. This filter will then be ANDed with fromAddress and toAddress.
Returns
Response Payload:
id: json-rpc id
jsonrpc: json-rpc version
result: an object with the following fields:
pageKey: uuid of next page of results (if exists, else blank).
transfers: array of objects (defined below) - sorted in ascending order by block number, ties broken by category (external , internal, token)
Object schema:
category: "external", "internal", "token", "erc20", "erc721", "erc1155" - label for the transfer
"token" includes "erc20" and "erc721" transfers
blockNum: the block where the transfer occurred (hex string).
from: from address of transfer (hex string).
to: to address of transfer (hex string). null if contract creation.
value: converted asset transfer value as a number (raw value divided by contract decimal). null if ERC721 transfer or contract decimal not available.
erc721TokenId: raw ERC721 token id (hex string). null if not an ERC721 token transfer
erc1155Metadata: A list of objects containing the ERC1155 tokenId (hex string) and value (hex string). null if not an ERC1155 transfer
asset: ETH or the token's symbol. null if not defined in the contract and not available from other sources.
hash: transaction hash (hex string).
rawContract
value: raw transfer value (hex string). null if ERC721 or ERC1155 transfer
address: contract address (hex string). null if external or internal transfer
decimal: contract decimal (hex string). null if not defined in the contract and not available from other sources.
​Example​
Request
Curl
Postman
1
curl https://eth-mainnet.alchemyapi.io/v2/your-api-key \
2
-X POST \
3
-H "Content-Type: application/json" \
4
-d'{"jsonrpc":"2.0", "id": 1, "method":"alchemy_getAssetTransfers","params":[{"fromBlock": "0xA97AB8", "toBlock": "0xA97CAC", "fromAddress": "0x3f5CE5FBFe3E9af3971dD833D26bA9b5C936f0bE", "contracts": ["0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"], "category": ["external", "internal", "token"], "maxCount": "0x5"}]}'
Copied!
1
URL: https://eth-mainnet.alchemyapi.io/v2/your-api-key
2
RequestType: POST
3
Body: 
4
{
5
  "jsonrpc": "2.0",
6
  "id": 0,
7
  "method": "alchemy_getAssetTransfers",
8
  "params": [
9
    {
10
      "fromBlock": "0xA97AB8",
11
      "toBlock": "0xA97CAC",
12
      "fromAddress": "0x3f5CE5FBFe3E9af3971dD833D26bA9b5C936f0bE",
13
      "contractAddresses": [
14
        "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"
15
      ],
16
      "maxCount": "0x5",
17
      "excludeZeroValue": true,
18
      "category": [
19
        "external",
20
        "token"
21
      ]
22
    }
23
  ]
24
}
Copied!
Result
1
{
2
  "id": 0,
3
  "result": {
4
    "transfers": [
5
      {
6
        "blockNum": "0xa97ae2",
7
        "hash": "0x6b0b85a7d202fbec16aea70f876298283b44b00629a3b472fbcadf2f9436e5fd",
8
        "from": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
9
        "to": "0xb4caa764e2bf087f1a7a0cec43250892022787d9",
10
        "value": 2.995,
11
        "erc721TokenId": null,
12
        "asset": "ETH",
13
        "category": "external",
14
        "rawContract": {
15
          "value": "0x299060a1be4b8000",
16
          "address": null,
17
          "decimal": "0x12"
18
        }
19
      },
20
      {
21
        "blockNum": "0xa97ae2",
22
        "hash": "0x8cc39a71b5da3abab46460a990f1e999e74428b4b075053f98d675656107f4f8",
23
        "from": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
24
        "to": "0x66ee6fc2c17b3a2624c06ae8783eb265a747a23d",
25
        "value": 0.1,
26
        "erc721TokenId": null,
27
        "asset": "ETH",
28
        "category": "external",
29
        "rawContract": {
30
          "value": "0x16345785d8a0000",
31
          "address": null,
32
          "decimal": "0x12"
33
        }
34
      },
35
      {
36
        "blockNum": "0xa97ae2",
37
        "hash": "0x8f8b1af8041b2c32eb4fb1b236c2523b28038c2a510ec48948749bc6bddf2824",
38
        "from": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
39
        "to": "0x8187d27641eaa9eca3a80f7a2f37af192fa43507",
40
        "value": 0.495,
41
        "erc721TokenId": null,
42
        "asset": "ETH",
43
        "category": "external",
44
        "rawContract": {
45
          "value": "0x6de97e09bd18000",
46
          "address": null,
47
          "decimal": "0x12"
48
        }
49
      },
50
      {
51
        "blockNum": "0xa97ae2",
52
        "hash": "0xb322ec7cf57d56b7250f36d7c59f0e7d96de05218ab402f345d4507829516f02",
53
        "from": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
54
        "to": "0xe535d87c42d21af3166eb00bbace668b13d55ec7",
55
        "value": 17.625,
56
        "erc721TokenId": null,
57
        "asset": "ETH",
58
        "category": "external",
59
        "rawContract": {
60
          "value": "0xf498941e66428000",
61
          "address": null,
62
          "decimal": "0x12"
63
        }
64
      },
65
      {
66
        "blockNum": "0xa97ae2",
67
        "hash": "0x56a00d5fac0dcacfe1cd950c49506712ec5bf319e246701321e8a92643da349d",
68
        "from": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
69
        "to": "0xfd5d6417fdcf02f0627aafa9e594a67d4485642d",
70
        "value": 5.73621309,
71
        "erc721TokenId": null,
72
        "asset": "ETH",
73
        "category": "external",
74
        "rawContract": {
75
          "value": "0x4f9b1f69e1655400",
76
          "address": null,
77
          "decimal": "0x12"
78
        }
79
      }
80
    ],
81
    "pageKey": "755207c2-d187-40fe-87aa-f43e71126777"
82
  },
83
  "jsonrpc": "2.0"
84
}
Copied!
Pagination
There are two cases in which pagination will be required:
1.If you have a specific number of responses that you want to receive in a given payload
2.If you receive a response with more than 1000 results.
In the first case, you should use the maxCount parameter in your request to specify the number of responses you wish to receive. If there are more results than specified in maxCount, you will receive a value for pageKey in your result which you should use to fetch the next response load by putting the returned pageKey value in the pageKey parameter of your next request. Continue to do so until a pageKey is no longer returned (meaning you've fetched all the results).
In the second case, you will also receive a value for pageKey in the response, which you should use to fetch the next 1000 (or however many is left) by putting the returned pageKey value in the pageKey parameter of your next request.
NOTE: Each page key has a TTL (Time to Live) of 10 minutes so if you receive a response with a pageKey value you must send the next request (with the pageKey) within the 10 minute window, otherwise you will have to restart the entire request cycle.