Console

POSTGet Token Balance Changes Within Range

Data APIhttps://web3.nodit.io/v1/aptos/mainnet/token/getTokenBalanceChangesWithinRange

Retrieves token balance change history within the specified block range.

Path Parameters
chainstring (enum)required

Parameter to specify the target chain for the query.

networkstring (enum)required

Parameter to specify the network of the target chain. Supported networks may vary depending on the chain.

Request Body
fromBlockstring

Parameter specifying the starting block for the query. You can enter one of the following formats:

  • block number: Enter block number as a decimal string.
  • block hash: 64-character hexadecimal (including "0x").
  • block tag: Use "earliest" or "latest" to specify the first block or the most recent block.

Notes:

  • This field cannot be used together with fromDate and toDate.
  • If provided without fromBlock, results are queried from genesis block to this block.
  • toBlock value cannot be less than fromBlock value.
  • If fromBlock and toBlock have the same value, only that block is queried.
  • "earliest" for toBlock is only allowed when fromBlock is "earliest".
  • If fromBlock and toBlock are not provided, the API queries data from the latest 30 days.
toBlockstring

Parameter specifying the ending block for the query. You can enter one of the following formats:

  • block number: Enter block number as a decimal string.
  • block hash: 64-character hexadecimal (including "0x").
  • block tag: Use "earliest" or "latest" to specify the first block or the most recent block.

Notes:

  • This field cannot be used together with fromDate and toDate.
  • If provided without fromBlock, results are queried from genesis block to this block.
  • toBlock value cannot be less than fromBlock value.
  • If fromBlock and toBlock have the same value, only that block is queried.
  • "earliest" for toBlock is only allowed when fromBlock is "earliest".
  • If fromBlock and toBlock are not provided, the API queries data from the latest 30 days.
fromDatestring

Parameter specifying the start date for the query. Date must follow ISO 8601 format (YYYY-MM-DDThh:mm:ss{time zone}) including seconds.

Notes:

  • If provided without toDate, results are queried from this date to the latest block.
  • fromDate value must be equal to or earlier than toDate value.
  • If fromDate and toDate have the same value, only blocks from that date are queried.
  • This field cannot be used together with fromBlock and toBlock.
  • If fromDate and toDate are not provided, the API queries data from the latest 30 days.
toDatestring

Parameter specifying the end date for the query. Date must follow ISO 8601 format (YYYY-MM-DDThh:mm:ss{time zone}) including seconds.

Notes:

  • If provided without fromDate, results are queried from genesis block to this date.
  • toDate value must be equal to or later than fromDate value.
  • If fromDate and toDate have the same value, only blocks from that date are queried.
  • This field cannot be used together with fromBlock and toBlock.
  • If fromDate and toDate are not provided, the API queries data from the latest 30 days.
pageinteger

The page parameter specifies the data page to query. It accepts values up to 100; for pages exceeding 100, use the cursor pagination method.

The page and cursor parameters cannot be used together. If both page and cursor are empty, cursor pagination is used.

rppinteger

rpp stands for results per page and specifies the page size. You can specify a number greater than 0 and up to 100.

cursorstring

The cursor parameter supports pagination and data navigation between pages. Provide the cursor value from the previous page in the next request to load the next page of data.

The page and cursor parameters cannot be used together. If both page and cursor are empty, cursor pagination is used.

withCountboolean

Parameter specifying whether to include the count field in the response. The count field indicates the total number of requested data items. When set to true, the count field is included and response speed may be slower.

Responses
pageinteger

Field representing the page number specified in the page parameter. This field is only included in the response when a value greater than 0 is specified for the page parameter.

rppinteger

Field representing the number of results per page specified in the rpp parameter.

cursorstring

A field for cursor pagination. This value must be provided in the next request to load the next page of data.

countinteger

Field representing the total count of requested data. This field is only included in the response when true is set for the withCount parameter.

fromDatestring

Field representing the start of the query range in Date mode. Returned in ISO 8601 format.

toDatestring

Field representing the end of the query range in Date mode. Returned in ISO 8601 format.

fromBlockinteger

Field representing the start block height of the query range in Block mode.

toBlockinteger

Field representing the end block height of the query range in Block mode.

fromLedgerinteger

Field representing the start ledger index of the query range in Ledger mode.

toLedgerinteger

Field representing the end ledger index of the query range in Ledger mode.

blockHeightinteger

A field that represents the height of the block containing this balance change. An integer that increments sequentially starting from the genesis block (0), used as an indicator for the blockchain length and the position of a specific block.

예: 160155267

blockTimestampinteger

A field that represents the block creation time. Provided as a UNIX timestamp, used for block creation order and time tracking. Block timestamps are used to ensure transaction order and measure inter-block creation intervals.

예: 1749003732416395

transactionHashstring

A field that represents the hash of the transaction that caused the balance change. A cryptographic hash computed from all transaction data, provided as a 64-character hexadecimal string prefixed with 0x. This hash enables retrieval of full information for the transaction related to the balance change.

예: 0x2a41cd44491bb92d4eb17d8487f82d9b43ab6289074c1986ee055be8105707c9

transactionVersioninteger

A field that represents the version of the transaction where the balance change occurred. A unique sequence ID indicating the order of the transaction on the chain, incrementing sequentially from 0.

예: 34872482

eventIndexintegerrequired

A field that represents the order index of the event within the transaction. Indicates the order of the current event among multiple events emitted in a single transaction. Starts at 0 and increments in event emission order; used to identify the order of events within the same transaction.

예: 0

eventTypestringrequired

A field that represents the type of the event. Provided as the full path (address::module::struct) of the event struct defined in the Move module. Used to identify the type of operation that caused the balance change.

예: 0x1::coin::WithdrawEvent

subEventIndexintegerrequired

A field that represents the order of asset changes when multiple asset changes occur within a single event. Identifies the order of multiple asset changes within an event sharing the same eventIndex. Starts at 0 and increments sequentially; plays an important role in complex asset operations (e.g., swaps).

예: 0

accountAddressstringrequired

A field that represents the address of the account where the balance change occurred. Provided as a 64-character hexadecimal string prefixed with 0x; identifies the account whose asset balance changed. This address is either the asset owner or the destination account the asset was transferred to.

예: 0x948592877d14d0fde0a42e2fc15a56959f30ea35d0b87c7ee8e98e0cce756f1a

assetTypestringrequired

A field that represents the type of the asset whose balance changed. Provided in one of two formats:

  • Coin: Asset ID in Move struct format (e.g., 0x1::aptos_coin::AptosCoin)
  • Fungible Asset: Object address that owns the metadata of the asset Used to uniquely identify the type of asset.

예: 0x1::aptos_coin::AptosCoin

linkedAssetTypestringrequired

A common identifier that links Coin and Fungible Asset when they have been migrated. This field serves as a unified key that groups Coin/Fungible Asset into a single asset unit for identification and retrieval, providing the Object address where the migrated Fungible Asset's Metadata is stored.

예: 0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b

changeValuestringrequired

A field that represents the balance change amount. Provided as a string in integer form.

  • Positive: indicates the account balance increased
  • Negative: indicates the account balance decreased The actual value must be interpreted considering decimals.

예: 1000000

tokenStandardstringrequired

A field that represents the standard type of the asset.

  • v1: Assets following the Coin standard
  • v2: Assets following the Fungible Asset standard

예: coin

transferTypestringrequired

A field that represents the transfer direction or action type. Indicates the specific type of balance change; the following values are possible:

  • deposit: asset deposit
  • withdraw: asset withdrawal
  • swap_in: deposit from swap
  • swap_out: withdrawal from swap
  • gas: gas fee payment
  • refund_gas: gas fee refund

예: deposit

X-API-KEY
RequestCU150
cURL
curl -X POST "https://web3.nodit.io/v1/aptos/mainnet/token/getTokenBalanceChangesWithinRange" \
  -H "X-API-KEY: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "fromDate": "2026-01-01T00:00:00Z",
  "toDate": "2026-02-01T00:00:00Z"
}'
Response
Example · 200
{
  "page": 0,
  "rpp": 0,
  "cursor": "string",
  "count": 0,
  "range": {
    "fromDate": "string",
    "toDate": "string",
    "fromBlock": 0,
    "toBlock": 0,
    "fromLedger": 0,
    "toLedger": 0
  },
  "items": [
    {
      "blockHeight": 160155267,
      "blockTimestamp": 1749003732416395,
      "transactionHash": "0x2a41cd44491bb92d4eb17d8487f82d9b43ab6289074c1986ee055be8105707c9",
      "transactionVersion": 34872482,
      "eventIndex": 0,
      "eventType": "0x1::coin::WithdrawEvent",
      "subEventIndex": 0,
      "accountAddress": "0x948592877d14d0fde0a42e2fc15a56959f30ea35d0b87c7ee8e98e0cce756f1a",
      "assetType": "0x1::aptos_coin::AptosCoin",
      "linkedAssetType": "0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b",
      "changeValue": "1000000",
      "tokenStandard": "coin",
      "transferType": "deposit"
    }
  ]
}

Last updated