Skip to main content
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 Circle 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 walks 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.
By default, there are no Monitored Tokens. This means that the system monitors all tokens as no filter exists. Calling GET /entity/config/monitoredTokens before configuring, returns 204, a no-content response.

​
Update Monitored Token List

To add tokens to the monitored token list, follow these steps:
  1. Retrieve the Token ID: Circle Wallets 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 retrieves 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.

​
USDC token IDs

BlockchainChain codeToken IDToken address
AptosAPTOS298eebe2-3131-5183-b528-f925f70848d00xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b
Aptos TestnetAPTOS-TESTNETe3cbdafc-42c3-58cc-ae4c-b31dbb10354c0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832
ArbitrumARBc87ffcb4-e2cf-5e67-84c6-388c965d2a660xaf88d065e77c8cc2239327c5edb3a432268e5831
Arbitrum SepoliaARB-SEPOLIA4b8daacc-5f47-5909-a3ba-30d171ebad980x75faf114eafb1bdbe2f0316df893fd58ce46aa4d
AvalancheAVAX7efdfdbf-1799-5089-a588-31beb97ba7550xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e
Avalanche FujiAVAX-FUJIff47a560-9795-5b7c-adfc-8f47dad9e06a0x5425890298aed601595a70ab815c96711a31bc65
BaseBASE915ce944-32df-5df5-a6b1-daa9b5069f960x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Base SepoliaBASE-SEPOLIAbdf128b4-827b-5267-8f9e-243694989b5f0x036CbD53842c5426634e7929541eC2318f3dCF7e
EthereumETHb037d751-fb22-5f0d-bae6-47373e7ae3e30xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
Ethereum SepoliaETH-SEPOLIA5797fbd6-3795-519d-84ca-ec4c5f80c3b10x1c7d4b196cb0c7b01d743fbc6116a902379c7238
PolygonMATICdb6905b9-8bcd-5537-8b08-f5548bdf79250x3c499c542cef5e3811e1192ce70d8cc03d5c3359
Polygon AmoyMATIC-AMOY36b6931a-873a-56a8-8a27-b706b17104ee0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582
SolanaSOL33ca4ef6-2500-5d79-82bf-e3036139cc29EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Solana DevnetSOL-DEVNET8fb3cadb-0ef4-573d-8fcd-e194f961c7284zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

​
Remove Monitored Tokens

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 are excluded from the list.

​
Update Monitor

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 is overwritten with the new tokens provided.

​
Change scope for Monitored Tokens

By default, all ERC-20, ERC-721, and ERC-1155 tokens deposited into your wallets are monitored and 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 are returned in the preceding 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 include details for all tokens in the wallet, irrespective of whether they are part of the monitored token list.
⌘I