Wallets

Monitored Tokens

The Monitored Tokens feature in the Programmable Wallet aims to empower developers with enhanced control over viewing token balances and transactions. This feature enables developers to easily manage and filter out tokens unrelated to their use case from our API responses, thereby selectively screening which tokens end-users can see, providing a more streamlined and personalized experience.

By utilizing the API endpoint POST config/entity/monitoredTokens, developers can easily add tokens via their unique token IDs. This guide will walk you through the steps to interact with the Monitored Tokens feature, including retrieving token IDs, adding tokens, and using API endpoints to get transaction and wallet balances for specific tokens.

To add tokens to the monitored token list, follow these steps:

  1. Retrieve the Token ID: Circle Wallets currently support native coins, ERC-20, ERC-721, and ERC-1155.

    • Each token deposited into the Circle Wallet generates a specific token ID, which developers can obtain through the following methods:
      • Documentation: Consult the table below for the USDC token ID.
      • Deposit Callback: The callback response includes the corresponding token ID when a token is deposited.
      • Querying Wallet Balance: GET /wallets/{id}/balances or GET /wallets/{id}/nfts will retrieve the tokens in the wallet and their related token IDs.
      • Querying Transaction: GET /transactions also retrieves the token IDs for inbound or outbound transactions.
  2. Add tokens into the monitored token list: Once you have the token ID, make a POST config/entity/monitoredTokens request with the token IDs specified in the required field.

BlockchainChain codeToken addressToken ID
EthereumETH0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48b037d751-fb22-5f0d-bae6-47373e7ae3e3
Ethereum SepoliaETH-SEPOLIA0x1c7d4b196cb0c7b01d743fbc6116a902379c72385797fbd6-3795-519d-84ca-ec4c5f80c3b1
ArbitrumARB0xaf88d065e77c8cc2239327c5edb3a432268e5831c87ffcb4-e2cf-5e67-84c6-388c965d2a66
Arbitrum SepoliaARB-SEPOLIA0x75faf114eafb1bdbe2f0316df893fd58ce46aa4d4b8daacc-5f47-5909-a3ba-30d171ebad98
PolygonMATIC0x3c499c542cef5e3811e1192ce70d8cc03d5c3359db6905b9-8bcd-5537-8b08-f5548bdf7925
Polygon AmoyMATIC-AMOY0x41e94eb019c0762f9bfcf9fb1e58725bfb0e758236b6931a-873a-56a8-8a27-b706b17104ee
AvalancheAVAX0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e7efdfdbf-1799-5089-a588-31beb97ba755
Avalanche FujiAVAX-FUJI0x5425890298aed601595a70ab815c96711a31bc65ff47a560-9795-5b7c-adfc-8f47dad9e06a
SolanaSOLEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v33ca4ef6-2500-5d79-82bf-e3036139cc29
Solana DevnetSOL-DEVNET4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU8fb3cadb-0ef4-573d-8fcd-e194f961c728

To remove tokens from Monitored Tokens, use POST /config/entity/monitoredTokens/delete to remove specific tokens. Specify the token IDs you want to delete, and they will be excluded from the list.

To replace tokens with Monitored Tokens, use PUT /config/entity/monitoredTokens to entirely replace the existing monitored token list by specifying the tokens you want to monitor. The previous list will be overwritten with the new tokens provided.

By default, all ERC-20, ERC-721, and ERC-1155 tokens deposited into your wallets are monitored and will be returned in GET /wallets/{id}/balances, GET /wallets/{id}/nfts, GET /transactions APIs, and webhook callbacks.

However, after adding tokens to Monitored Tokens, the Monitored Tokens scope is set to SELECTED by default, which means only the provided tokens will be returned in the above APIs and callbacks. To revert to monitoring all tokens, call PUT /config/entity/monitoredTokens/scope and set the scope to MONITOR_ALL.

It’s important to note that even when the monitored token scope is set with SELECTED, developers can view all tokens in the wallet balance and transactions. This can be achieved by setting the includeAll field to True (default value is False) in the GET /wallets/{id}/balances, GET /wallets/{id}/nfts, GET /transactions APIs. By doing so, the API responses will include details for all tokens in the wallet, irrespective of whether they are part of the monitored token list.

Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.