Skip to main content
API docs by Redocly

Web API (v1)

Download OpenAPI specification:Download

Overview

The MetaMask Institutional Web API lets you retrieve your transactions history and snapshots of your portfolio valuations, automate reporting, or build your own applications. To get started:

  1. Log in the dashboard
  2. Visit the page API
  3. Generate your API key
  4. Use the API key in your HTTP requests

Authorization

ApiKey

To ensure secure access to our REST API, you need to authenticate your requests with an API key. To generate your API key, visit the page API in the dashboard. Include the API key in the header X-Api-Key on your HTTP requests.

The following example uses cURL to get a snapshot using the GET /snapshots/{snapshotId} endpoint:

curl --request GET \
  --url 'https://api.metamask-institutional.io/snapshots/{snapshotId}' \
  --header 'X-Api-Key: <APIKEY>'

You can use any programming language:

import axios from "axios";

const options = {
  method: 'GET',
  url: 'https://api.metamask-institutional.io/snapshots/{snapshotId}',
  headers: {'X-Api-Key': '<APIKEY>'}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
  • Do not share your API key. Treat it like a password.
  • If you lost your API key, rotate it via the page API in the dashboard.
  • If you believe your API key has been compromised, rotate it via the page API in the dashboard.
  • Failure to include the API key in your requests will result in an authentication error.
Security Scheme Type: API Key
Header parameter name: X-Api-Key

Rate Limits

Excessive Web API requests in a short duration may trigger a 429 error response from MetaMask Institutional, indicating that your API key has hit our rate limit. We enforce these limits to ensure the stability of our API.

Our API rate limit is determined by the number of calls your application makes within a rolling 1-second window. Exceeding this limit will result in 429 error responses, potentially leading to unexpected behavior in your application. The limit varies based on your MetaMask Institutional subscription.

Throttling is an effective strategy to ensure your application stays within the rate limits. It involves limiting the number of API requests your application can make in a given amount of time. This can be achieved by implementing a delay between requests or queuing requests and processing them at a fixed rate.

There are several libraries available that can help you implement throttling in your application:

  • For Node.js, consider using the Bottleneck library. It's a powerful, easy-to-use rate limiter that you can use to control the rate of API requests.
  • For Python, you might want to use ratelimiter, which offers a simple and flexible rate limiting implementation.
  • For Java, Bucket4j is a powerful library that supports multiple rate limiting algorithms.
  • For Ruby, ratelimit is a straightforward rate limiter that's easy to integrate into any application.

Remember, the key to successful throttling is to balance between staying within the rate limits and providing a smooth user experience.

Monthly Quotas

Each API key on the MetaMask Institutional Web API is subject to a monthly quota, which is determined by your subscription level. For example, an API key may be allocated a quota of 1,000 requests per month.

At the commencement of each new month, the usage count is reset to zero, providing a fresh quota for the month ahead.

It's important to note that even after reaching the monthly quota, the API key remains active. You can continue to make requests using the same API key. However, any requests beyond the quota will incur additional charges, referred to as overage fees. Please review your subscription details for information on these fees.

Support

If you have any questions or run into any issues while using the MetaMask Institutional Web API, you can find help in the MetaMask Institutional Knowledge Base, or Contact Support to get in touch with our support team.

Legal

By using MetaMask Institutional Web API, you accept the Terms and Conditions.

Account

Manage your MMI account.

Addresses saved in the account are included in automatic snapshots and have their transaction history monitored. Addresses involved in transactions the customer made through the MMI extension are automatically added to this list. Additionally, customers have the option to append addresses by utilizing the endpoint PUT /account/addresses.

You don't need to own the signing keys of an address to save it in your account.

Get Addresses

Retrieves a list of blockchain addresses saved in the current customer's account.

Authorizations:
ApiKey

Responses

Request samples 

curl --request GET \
  --url https://api.metamask-institutional.io/account/addresses \
  --header 'X-Api-Key: <APIKEY>'

Response samples

Content type
application/json
[
  • {
    }
]

Get Current AUD

Fetch the current portoflio valuation, in US Dollars of the customer.

The valuation at the specified date is determined by valuing all assets within the customer's addresses. Including, the dollar value of any token assets, NFT dollar floor prices, dollar value of any DeFi assets (less the dollar value of any DeFi debts), dollar value of any rewards or other accruals, and the dollar value of staking positions and staking rewards.

Authorizations:
ApiKey

Responses

Request samples 

curl --request GET \
  --url https://api.metamask-institutional.io/account/aud \
  --header 'X-Api-Key: <APIKEY>'

Response samples

Content type
application/json
{
  • "total": 0,
  • "tokenBalances": 0,
  • "deFiPositions": 0,
  • "nftCollections": 0
}

Remove Several Addresses

Remove one or more blockchain addresses from the customer's account in a single request. Useful to clean up addresses that are no longer needed or were added erroneously.

Important: Removal of addresses from the account will exclude them from future automatic snapshots.

Authorizations:
ApiKey
Request Body schema: application/json
required
Array
address
string (Caip10AccountId)

Represents a blockchain account using the CAIP-10 format, as defined in the CAIP-10 standard. The format is caip2_namespace:caip2_reference:account_address, where:

  • caip2_namespace identifies the blockchain namespace.
  • caip2_reference specifies the reference identifier for the blockchain.
  • account_address is the specific account address on the blockchain.

Supported namespaces and references include:

  • eip155:1:account_address for Ethereum Mainnet, where 1 is the chain ID for Ethereum Mainnet.
  • eip155:42:account_address for Kovan Testnet, an example of an Ethereum test network with chain ID 42.
  • eip155:<x>:account_address for any EVM (Ethereum Virtual Machine) compatible blockchain. Replace <x> with the chain ID specific to that blockchain. This allows for flexibility in supporting various EVM-compatible chains.
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:account_address for Solana, where solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp is the Solana Mainnet.

Note: Adding a new address in the format eip155:1:0xXXX automatically associates it with all EVM-compatible blockchains. This feature allows for broader compatibility and simplifies address management across different networks.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "statusCode": 204,
  • "message": "No Content"
}

Save Several Addresses

Save new blockchain addresses to the customer's account or update details of existing addresses. This endpoint accepts a list of address objects. Each object can represent a new address to be added or updates to an existing address, such as changing its name or visibility (hidden attribute).

This endpoint supports the following operations:

  • Saving New Addresses: Submit address objects with unique address not previously associated with the customer's account.

  • Updating Existing Addresses: To update an address, submit an address object with the same address as an existing entry. Modify the name and/or hidden fields as desired.

Authorizations:
ApiKey
Request Body schema: application/json
required
Array
address
string (Caip10AccountId)

Represents a blockchain account using the CAIP-10 format, as defined in the CAIP-10 standard. The format is caip2_namespace:caip2_reference:account_address, where:

  • caip2_namespace identifies the blockchain namespace.
  • caip2_reference specifies the reference identifier for the blockchain.
  • account_address is the specific account address on the blockchain.

Supported namespaces and references include:

  • eip155:1:account_address for Ethereum Mainnet, where 1 is the chain ID for Ethereum Mainnet.
  • eip155:42:account_address for Kovan Testnet, an example of an Ethereum test network with chain ID 42.
  • eip155:<x>:account_address for any EVM (Ethereum Virtual Machine) compatible blockchain. Replace <x> with the chain ID specific to that blockchain. This allows for flexibility in supporting various EVM-compatible chains.
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:account_address for Solana, where solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp is the Solana Mainnet.

Note: Adding a new address in the format eip155:1:0xXXX automatically associates it with all EVM-compatible blockchains. This feature allows for broader compatibility and simplifies address management across different networks.

hidden
boolean

Sets whether the entity is hidden from the Portfolio Dashboard views.

name
string or null

Sets a human-readable name for the entity.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

DeFi

Get detailed Profit & Loss data on open DeFi positions.

Get Positions / Get Profits

A JSON-RPC endpoint that supports two distinct methods:

  • Get Positions: Get a structured overview of the open DeFi positions linked to the specified address, at current time or at specific past block. In the JSON body, use { "method": "positions", ... }.
  • Get Profits: Get a structured overview of performance (%) and USD profits of the specified address' DeFi positions, at current time or at specific past block. In the JSON body, use { "method": "profits", ... }.

The information is provided from a routinely refreshed cache. To insistently retrieve the most recent data, include the flag { "ignoreCache": true }.

Authorizations:
ApiKey
Request Body schema: application/json
required
One of
ignoreCache
boolean
Default: false

Optionally set this flag to true to insistently retrieve the most recent data instead of cached data.

method
required
string
Value: "positions"

The JSON-RPC method. Must be "positions".

required
object

Responses

Request samples

Content type
application/json
Example
{
  • "method": "positions",
  • "params": {
    },
  • "ignoreCache": false
}

Response samples

Content type
application/json
{
  • "createdAt": "2024-01-12T08:25:56.455Z",
  • "updatedAt": "2024-01-12T08:25:56.455Z",
  • "data": [
    ]
}

Snapshots

Retrieve valuations of your assets at specific times across your addresses.

The scope of each snapshot is determined by its creation method:

  • Automatically Created: Covers all addresses saved in the customer's account.
  • Manually Created: Covers the addresses passed in the POST /snapshots request body.

Create Snapshot

Initiate the creation of a new snapshot. Please note that the exact timing of the snapshot creation is not guaranteed. This is because the request is queued and processed asynchronously.

Responds with the ID of the snapshot to be created.

After this request responded successfully, wait some time for the snapshot to be created, and query the endpoint GET /snapshots/{snapshotId} to get its content. It typically takes between a few seconds and a few minutes, depending on how busy the queue is.

Snapshot data is cached for a period of 1 hour. This means that repeated requests within this timeframe will create new snapshots with the same data. After the cache period expires, a new request will create a snapshot with fresh data.

Authorizations:
ApiKey
Request Body schema: application/json
optional
addresses
Array of strings

An optional array of Blockchain addresses. Limits the scope of the snapshot to this list of addresses, instead of all the addresses saved in the customer's account. When empty, defaults to all the addresses saved in the customer's account. Every address must be part of the addresses saved in the customer's account. Every address must be valid for one of EVM,Solana,Bitcoin.

Responses

Request samples

Content type
application/json
{
  • "addresses": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "94b2a0cf-5bb2-4bfd-8bc3-9aa48bbfa4ec"
}

Get Snapshot

Get a comprehensive overview of the customer's portfolio's positions and valuations at a given time. Includes token balances, DeFi positions and NFT collections. The snapshot IDs can be found using the endpoint GET /snapshots.

The endpoint can return data in various MIME types:

  • To get data as JSON, do not set the header Accept, or set it to Accept: application/json or Accept: */*
  • To download as a binary .xlsx file, set the header Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorizations:
ApiKey
path Parameters
snapshotId
required
string
query Parameters
currency
string
Example: currency=usd

The currency to get the price values in.

Responses

Request samples 

curl --request GET \
  --url 'https://api.metamask-institutional.io/snapshots/{snapshotId}currency=usd' \
  --header 'X-Api-Key: <APIKEY>'

Response samples

Content type
application/json
{
  • "id": "af261deb-1b94-4fb8-a713-6afaa438849e",
  • "addresses": [
    ],
  • "cefiAccounts": [
    ],
  • "accountBundles": [
    ],
  • "createdAt": "2024-08-27T11:48:41+02:00",
  • "creationMode": "manual",
  • "customer": {
    },
  • "data": {
    }
}

Search Snapshot IDs

Fetch a paginated list containing the IDs of snapshots associated with a specific customer, matching the search filters. The IDs can then be used to fetch the actual snapshot content with GET /snapshots/{snapshotId}.

Authorizations:
ApiKey
query Parameters
fromTimestamp
string
Example: fromTimestamp=2023-10-25T13:36:45+02:00

The start date and time for the range of snapshots to retrieve, formatted as an ISO 8601 string.

Depending how you run the query, you might need to URL-encode this parameter. For instance 2023-10-25T13:36:45+02:00 would become 2023-10-25T13%3A36%3A45%2B02%3A00.

order
string
Enum: "asc" "desc"

The order to sort the snapshots in.

page
number >= 1
Example: page=1

The page number to retrieve in the paginated list of snapshots.

perPage
number >= 10
Example: perPage=10

The number of snapshots to retrieve per page.

sort
string
Enum: "createdAt" "updatedAt"

The property to sort the snapshots by.

toTimestamp
string
Example: toTimestamp=2023-10-26T13:36:45+02:00

The end date and time for the range of snapshots to retrieve, formatted as an ISO 8601 string.

Depending how you run the query, you might need to URL-encode this parameter. For instance 2023-10-26T13:36:45+02:00 would become 2023-10-26T13%3A36%3A45%2B02%3A00.

Responses

Request samples 

curl --request GET \
  --url 'https://api.metamask-institutional.io/snapshots?fromTimestamp=2023-10-25T13%3A36%3A45%2B02%3A00&toTimestamp=2023-10-26T13%3A36%3A45%2B02%3A00&page=2&perPage=10&sort=createdAt&order=asc' \
  --header 'X-Api-Key: <APIKEY>'

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "items": [
    ]
}

Transactions

The past transactions related to addresses that have transacted through MMI or added to customer's accounts.

Search Transactions

Search trough all types of asset transfers. It provides a comprehensive tool for analyzing transaction history across various blockchains, allowing for detailed insights into transactions based on a wide range of criteria, including sender and receiver addresses, chain IDs, timestamps, asset types, and more.

You must always provide at least one of the body params from, to, or transactionHashes.

Note: This search functionality retrieves transactions related to addresses that have been used in transactions through the MMI extension or that are added to the customer's account.

Note: A POST request is used here instead of a GET to accommodate an arbitrary number of addresses in the filters from/to/contractAddresses/transactionHashes without running into URL length limitations.

Note: There may be a brief delay of a few seconds before a transaction becomes available after being included in a block. This is due to the asynchronous indexing process.

Authorizations:
ApiKey
query Parameters
page
number
Default: 1
Example: page=1

The page of results being requested

perPage
number
Default: 50
Example: perPage=50

The number of results per page

Request Body schema: application/json
required
assetTypes
Array of strings
Items Enum: "native" "nft" "token"

Leave empty to retrieve all types of assets supported by the chain. Or specify the list of desired asset types.

blockNumbers
Array of numbers

Limit the results to transactions included in the defined blocks numbers.

chainIds
Array of numbers

List of chain IDs where to search the transactions in. Supported chain IDs are:

  • avalanche: 43114
  • arbitrum: 42161
  • aurora: 1313161554
  • bsc: 56
  • celo: 42220
  • cronos: 25
  • fantom: 250
  • ethereum: 1
  • moonbeam: 1284
  • moonriver: 1285
  • optimism: 10
  • polygon: 137
  • linea: 59144
  • base: 8453

contractAddresses
Array of strings[/^0x[a-fA-F0-9]{40}$/]

Limit the results to transfers of tokens with contract address in the list.

excludeContracts
Array of strings[/^0x[a-fA-F0-9]{40}$/]

Addresses to filter out transactions with matching contractAddress.

from
Array of strings[/^0x[a-fA-F0-9]{40}$/]

Source addresses

fromTimestamp
string

The start date and time for the range of transactions to retrieve, formatted as an ISO 8601 string.

hideSpam
boolean
Default: false

Hide transactions with known spam addresses

to
Array of strings[/^0x[a-fA-F0-9]{40}$/]

Destination addresses

tokenIds
Array of strings

Limit the results to transfers of NFTs token ID in the list.

toTimestamp
string

The end date and time for the range of transactions to retrieve, formatted as an ISO 8601 string.

transactionHashes
Array of strings[/^0x[a-fA-F0-9]{64}$/]

Limit the results to transactions with a hash in the list.

Responses

Request samples

Content type
application/json
{
  • "from": [
    ],
  • "to": [
    ],
  • "chainIds": [
    ],
  • "fromTimestamp": "2022-10-25T13:36:45+02:00",
  • "toTimestamp": "2023-10-26T13:36:45+02:00",
  • "assetTypes": [
    ],
  • "contractAddresses": [
    ],
  • "tokenIds": [
    ],
  • "transactionHashes": [
    ],
  • "blockNumbers": [
    ],
  • "excludeContracts": [
    ],
  • "hideSpam": false
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "items": [
    ]
}

Address

address
required
string

The blockchain address.

createdAt
string <date-time>

The timestamp when the entity was created.

object

Details about the custodian responsible for managing the signing keys of the address.

hidden
required
boolean

Indicates whether the entity is hidden from the Portfolio Dashboard views.

id
required
string

A unique identifier for the entity.

name
string or null

A human-readable name for the entity, specified by the customer at creation.

namespace
required
string

The CAIP-2 namespace of the blockchain network the address belongs to.

updatedAt
string <date-time>

The timestamp when the entity was last updated.

{
  • "id": "f32e96af-9a91-4c3b-938a-42f3df18e270",
  • "namespace": "eip155:1",
  • "address": "0xC71E8d9c352512540A94a0b85582a96f82aC7b4e",
  • "name": "My Address 1",
  • "hidden": false,
  • "custodian": {
    },
  • "createdAt": "2023-12-11T14:30:10.960Z",
  • "updatedAt": "2024-02-28T10:39:48.150Z"
}

Position

chainId
required
integer

Blockchain ID where the protocol operates (e.g., 1, 10, 56).

description
required
string

Brief description of the protocol adapter.

error
object

Present in the second item if success is false, providing an error message and details.

iconUrl
required
string <uri>

URL of the protocol's icon.

name
required
string

Display name of the protocol.

positionType
required
string (PositionType)
Enum: "borrow" "fiat-prices" "lend" "reward" "stake" "supply"

Type of position. It can be one of the following:

  • supply: Liquidity position e.g. a dex pool
  • lend: Providing liquidity to a lending and borrow protocol
  • borrow: Getting a loan from a lending and borrow protocol
  • stake: Staking a token e.g. staking eth or staking an lp token
  • reward: Claimable rewards, these type of positions will be merged with the equivalent lp position
  • fiat-prices: Fiat prices
productId
required
string

Identifier for the specific product within the protocol.

protocolId
required
string

Identifier of the DeFi protocol.

siteUrl
required
string <uri>

URL of the protocol's website.

success
required
boolean

Boolean indicating if the query was successful.

required
Array of objects (Token)

An array of token objects, detailing each token's information like address, name, symbol, balance, and nested token details.

{
  • "protocolId": "aave-v2",
  • "name": "Aave V2",
  • "description": "Aave V2 is a decentralized non-custodial money market protocol.",
  • "siteUrl": "https://aave.com/",
  • "iconUrl": "https://aave.com/favicon.ico",
  • "positionType": "lend",
  • "chainId": 1,
  • "productId": "aave-v2-product-1",
  • "success": true,
  • "tokens": [],
  • "error": { }
}

Profit

chainId
required
integer

Blockchain ID where the protocol operates (e.g., 1, 10, 56).

description
required
string

Brief description of the protocol adapter.

error
object

Present in the second item if success is false, providing an error message and details.

fromBlock
required
integer

Starting block for the snapshot.

iconUrl
required
string <uri>

URL of the protocol's icon.

name
required
string

Display name of the protocol.

positionType
required
string (PositionType)
Enum: "borrow" "fiat-prices" "lend" "reward" "stake" "supply"

Type of position. It can be one of the following:

  • supply: Liquidity position e.g. a dex pool
  • lend: Providing liquidity to a lending and borrow protocol
  • borrow: Getting a loan from a lending and borrow protocol
  • stake: Staking a token e.g. staking eth or staking an lp token
  • reward: Claimable rewards, these type of positions will be merged with the equivalent lp position
  • fiat-prices: Fiat prices
productId
required
string

Identifier for the specific product within the protocol.

protocolId
required
string

Identifier of the DeFi protocol.

siteUrl
required
string <uri>

URL of the protocol's website.

success
required
boolean

Boolean indicating if the query was successful.

toBlock
required
integer

Ending block for the snapshot.

required
Array of objects (Token)

An array of token objects, empty in the first item and populated in the third. For each token, details like address, name, symbol, type, profit, performance, and calculation data are provided.

{}

Transaction

assetType
required
string
Enum: "native" "nft" "token"

Type of asset being transacted.

blockHash
required
string

Hash of the block where this transaction was in.

blockNumber
required
number

Block number where this transaction was in.

category
required
string
Enum: "0X_V3_EXCHANGE" "1INCH_EXCHANGE" "1INCH_V3_EXCHANGE" "AAVE_BORROW" "AAVE_DEPOSIT" "AAVE_REPAY" "AAVE_WITHDRAW" "ARBITRUM_BRIDGE_IN" "ARBITRUM_BRIDGE_OUT" "BALANCER_CLAIM" "BALANCER_DEPOSIT" "BALANCER_EXCHANGE" "BALANCER_WITHDRAW" "COMPOUND_CLAIM" "COMPOUND_V2_BORROW" "COMPOUND_V2_DEPOSIT" "COMPOUND_V2_REPAY" "COMPOUND_V2_WITHDRAW" "DAPPNODE_CLAIM" "DEX_AG_EXCHANGE" "ENS_CLAIM" "ENS_DOMAIN_REGISTER" "ENS_DOMAIN_RENEW" "ENS_DOMAIN_RESOLVER_SET" "ENS_DOMAIN_TRANSFER" "ERC_20_APPROVE" "ERC_20_MINT" "ERC_20_TRANSFER" "ERC_721_APPROVE" "ERC_721_MINT" "ERC_721_TRANSFER" "ETHERMINE_MINING_PAYOUT" "FUTURESWAP_GOVERNANCE_VOTE" "GITCOIN_CLAIM" "GNOSIS_SAFE_APPROVE_TX" "GNOSIS_SAFE_WITHDRAW" "IDEX_DEPOSIT_ETH" "IDEX_DEPOSIT_TOKEN" "IDEX_WITHDRAW" "KYBER_EXCHANGE" "METAMASK_STAKE_V1" "METAMASK_V1_BRIDGE_OUT" "METAMASK_V1_EXCHANGE" "MININGPOOLHUB_MINING_PAYOUT" "OPENSEA_CANCEL_ORDER" "OPENSEA_EXCHANGE" "OPENSEA_REGISTER" "PARASWAP_V4_EXCHANGE" "POLYGON_BRIDGE_IN" "POLYGON_BRIDGE_OUT" "POOLTOGETHER_CLAIM" "POOLTOGETHER_DEPOSIT" "POOLTOGETHER_WITHDRAW" "SHAPESHIFT_CLAIM" "SPARKPOOL_MINING_PAYOUT" "SUSHISWAP_DEPOSIT" "SUSHISWAP_EXCHANGE" "SUSHISWAP_WITHDRAW" "TORNADO_CASH_V1_DEPOSIT" "TORNADO_CASH_V1_WITHDRAW" "TO_0X_EXCHANGE_PROXY" "TO_1INCH_V3_EXCHANGE_PROXY" "TO_ARBITRUM_INBOX" "TO_ARBITRUM_OUTBOX" "TO_BALANCER_DISTRIBUTOR" "TO_COMPOUND_COMPTROLLER" "TO_DAPPNODE_DISTRIBUTOR" "TO_ENS_REGISTRAR" "TO_ENS_TOKEN_CONTRACT" "TO_FOX_DISTRIBUTOR" "TO_FUTURESWAP_GOVERNANCE" "TO_GITCOIN_DISTRIBUTOR" "TO_METAMASK_BRIDGE_V1" "TO_METAMASK_STAKE_V1" "TO_METAMASK_V1_ROUTER" "TO_OPENSEA_REGISTRY" "TO_OPENSEA_ROUTER" "TO_PARASWAP_V4_EXCHANGE_PROXY" "TO_POLYGON_BRIDGE" "TO_POOLTOGETHER_DISTRIBUTOR" "TO_SUSHISWAP_ROUTER" "TO_UNISWAP_DISTRIBUTOR" "TO_UNISWAP_V2_ROUTER" "TO_UNISWAP_V3_ROUTER" "UNISWAP_CLAIM" "UNISWAP_V1_DEPOSIT" "UNISWAP_V1_EXCHANGE" "UNISWAP_V1_WITHDRAW" "UNISWAP_V2_DEPOSIT" "UNISWAP_V2_EXCHANGE" "UNISWAP_V2_WITHDRAW" "UNISWAP_V3_DEPOSIT" "UNISWAP_V3_EXCHANGE" "UNISWAP_V3_WITHDRAW" "WETH_UNWRAP" "WETH_WRAP"

Categorizes the type of transaction or operation. The categories cover a wide range of activities in the Ethereum ecosystem, including different types of exchanges (like 0x, 1inch), lending platforms (like Aave, Compound), domain name services (like ENS), and more. Each category represents a specific type of operation or interaction with a specific protocol or service.

chainId
required
number

Decimal ID of the chain where the transaction happened.

confirmations
required
number

The number of blocks in the blockchain that have been confirmed and added after the block that this transaction is part of. A higher number of confirmations indicates a greater assurance that the transaction is final, as it means more blocks have been added after it.

contractAddress
required
string/^0x[a-fA-F0-9]{40}$/

Address of the token's contract, in case of a token transfer.

cumulativeGasUsed
required
string

The total amount of gas used when the transaction was executed in the block. It is cumulative because it includes the gas used by all preceding transactions in the block.

fee
required
string

Fee in Wei that the transaction cost. Is equal to gasUsed * gasPrice.

feeUsd
required
string

Fee in US dollars that the transaction cost, using the price in US dollars of the chain's native token at the time of the transaction. Is equal to gasUsed * gasPrice * nativeTokenPriceUsd.

from
required
string/^0x[a-fA-F0-9]{40}$/

Address of the sender.

gas
required
string

Gas provided by the sender.

gasPrice
required
string

Gas price provided by the sender in Wei.

gasUsed
required
string

The amount of gas that was used by this specific transaction.

hash
required
string/^0x[a-fA-F0-9]{64}$/

Hash of the transaction.

id
required
string

Unique identifier for the transaction

input
required
string

The data send along with the transaction.

isError
required
boolean

Whether it was successfull or rejected/cancelled.

methodId
required
string

The contract identifier for the function that was called in this transaction. It is derived from the first 4 bytes of the Keccak (SHA-3) hash of the ASCII form of the function signature.

nativeTokenPriceUsd
required
number

Price in US dollars of the chain's native token at the time of the transaction.

nftCollectionIconUrl
required
string

The URL of the icon or image associated with the NFT collection.

nftCollectionName
required
string

The name of the collection to which the NFT belongs.

nftCollectionSymbol
required
string

The symbol of the collection to which the NFT belongs.

nftCollectionTokenId
required
string

The unique identifier of the token within its NFT collection. This ID is unique within the specific collection and is used to reference the individual NFT.

nonce
required
number

The number of transactions made by the sender prior to this one.

notes
required
string

This field contains any additional comments or notes that the user included when signing the transaction through the custodian. It provides context or details about the transaction that may be relevant for record-keeping or auditing purposes.

timestamp
required
string <date-time>

Unix timestamp in seconds of the block this transaction was in.

to
required
string/^0x[a-fA-F0-9]{40}$/

Address of the receiver.

tokenDecimals
required
number

The number of decimal places that the token can be divided into.

tokenIconUrl
required
string

URL of the token/NFT icone, in case of a transfer.

tokenName
required
string

Name of the token/NFT, in case of a transfer.

tokenPriceInNativeToken
required
number

The current price of the token in terms of the chain's native token (for instance Ether for Ethereum mainnnet).

tokenPriceUsd
required
number

The current price of the token in terms of US dollars.

tokenSymbol
required
string

Symbol of the token/NFT, in case of a transfer.

transactionIndex
required
number

Integer of the transaction index position in the block.

userCategory
required
string
value
required
string

Value transferred in Wei.

{
  • "id": "017f3026f6e79427c81a67e438f5be50c0940e019406cde36f571c3d53f70786",
  • "chainId": 1,
  • "hash": "0xe3852b9c47f651395d4d6a8f517c6f2f6ecb44445684fc32ef08155bacb62c68",
  • "transactionIndex": 14,
  • "blockNumber": 14732481,
  • "blockHash": "0x88b44988a25ce40d55c1a621e3ff9c86504fa3878489f4bbd88af8a6c88fe0e6",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "nonce": 457,
  • "from": "0xfc75970a11669c571a4b8f8abeceeecffa5dc7ea",
  • "to": "0x8d203862455269aa79e2d5b7974d0816673f4e2c",
  • "value": "81689008581039686",
  • "gas": "31000",
  • "gasUsed": "21000",
  • "gasPrice": "1000000000",
  • "isError": true,
  • "input": "0x",
  • "contractAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  • "cumulativeGasUsed": "1086011",
  • "confirmations": 4382,
  • "methodId": "0x095ea7b3",
  • "assetType": "native",
  • "notes": "Payment for services rendered",
  • "nativeTokenPriceUsd": 1600,
  • "fee": "31000000000000",
  • "feeUsd": "0.11",
  • "category": "0X_V3_EXCHANGE",
  • "userCategory": "swap",
  • "tokenName": "PepeCoin",
  • "tokenSymbol": "PEPE",
  • "tokenIconUrl": "https://s3.metamask-institutional.io/tokens/pepe.png",
  • "tokenDecimals": 18,
  • "tokenPriceInNativeToken": 200,
  • "tokenPriceUsd": 0.16,
  • "nftCollectionName": "The Merge: Regenesis",
  • "nftCollectionSymbol": "MERGE",
  • "nftCollectionIconUrl": "https://img-hester.xyz/metadata.json",
  • "nftCollectionTokenId": "1"
}
Last updated on by Xavier Brochard