relay_get_currencies
Retrieve token currency metadata with flexible filters—chain IDs, search terms, addresses, verification status, and deposit address support—to find specific tokens across multiple blockchains.
Instructions
Get currencies metadata from a curated list. Supports filtering by chain IDs, search terms, addresses, and other criteria.
Common Examples: • Find USDC on specific chains: {"chainIds": [1, 10, 8453], "term": "usdc", "verified": true, "limit": 10} • All major tokens on Ethereum: {"chainIds": [1], "defaultList": true, "limit": 20} • Search by contract address: {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "includeAllChains": true} • Verified tokens only: {"verified": true, "limit": 50} • Deposit-address supported tokens: {"depositAddressOnly": true}
Tip: Use verified=true to avoid scam/fake tokens. Use term to search by symbol/name.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| defaultList | No | Return default currencies from curated list | |
| chainIds | No | Chain IDs to search for currencies (e.g., [1, 10, 137] for Ethereum, Optimism, Polygon) | |
| term | No | Search term for currencies (symbol, name, or partial match) | |
| address | No | Token contract address to search for | |
| currencyId | No | Specific currency ID to retrieve | |
| tokens | No | List of token identifiers in format chainId:address (e.g., ["1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"]) | |
| verified | No | Filter for verified currencies only (recommended to avoid scam tokens) | |
| limit | No | Limit the number of results (default: 20, max: 100) | |
| includeAllChains | No | Include all chains for a currency when filtering by chainId and address | |
| useExternalSearch | No | Use 3rd party APIs to search for tokens not indexed by Relay | |
| depositAddressOnly | No | Return only currencies supported with deposit address bridging |
Implementation Reference
- src/tools/currencies.ts:86-184 (registration)Registers the 'relay_get_currencies' tool via createCurrencyTools(), which returns an object with name, description, inputSchema, and handler properties.
export function createCurrencyTools(client: RelayClient) { return { /** * MCP Tool: Get currency metadata from curated token list * * Provides comprehensive token discovery across all supported blockchain networks * with advanced filtering capabilities. This tool is essential for finding * token contract addresses needed for quotes, price queries, and swaps. * * Key Features: * - Search by token symbol, name, or contract address * - Filter by blockchain networks (chain IDs) * - Verified token filtering to avoid scams/fakes * - Default curated token lists for major tokens * - External search capabilities for unlisted tokens * - Deposit address bridging support filtering * - Comprehensive metadata including decimals, logos, verification status * * Search Capabilities: * - Text Search: Find tokens by symbol (e.g., "USDC", "ETH", "WBTC") * - Address Search: Look up tokens by contract address * - Chain Filtering: Limit results to specific blockchain networks * - Verification: Filter for verified/trusted tokens only * - Cross-Chain: Find the same token across multiple chains * * Common Use Cases: * - Find token contract addresses for quote generation * - Discover available tokens on specific chains * - Verify token authenticity and metadata * - Search for bridgeable tokens between chains * - Find tokens that support deposit address bridging * * Security Best Practices: * - Always use verified=true to avoid scam tokens * - Cross-reference contract addresses from official sources * - Use defaultList=true for major, well-known tokens * - Verify token symbols match expected tokens */ relay_get_currencies: { name: 'relay_get_currencies', description: 'Get currencies metadata from a curated list. Supports filtering by chain IDs, search terms, addresses, and other criteria.\n\nCommon Examples:\n• Find USDC on specific chains: {"chainIds": [1, 10, 8453], "term": "usdc", "verified": true, "limit": 10}\n• All major tokens on Ethereum: {"chainIds": [1], "defaultList": true, "limit": 20}\n• Search by contract address: {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "includeAllChains": true}\n• Verified tokens only: {"verified": true, "limit": 50}\n• Deposit-address supported tokens: {"depositAddressOnly": true}\n\nTip: Use verified=true to avoid scam/fake tokens. Use term to search by symbol/name.', inputSchema: { type: 'object', properties: { defaultList: { type: 'boolean', description: 'Return default currencies from curated list' }, chainIds: { type: 'array', items: { type: 'number' }, description: 'Chain IDs to search for currencies (e.g., [1, 10, 137] for Ethereum, Optimism, Polygon)' }, term: { type: 'string', description: 'Search term for currencies (symbol, name, or partial match)' }, address: { type: 'string', description: 'Token contract address to search for' }, currencyId: { type: 'string', description: 'Specific currency ID to retrieve' }, tokens: { type: 'array', items: { type: 'string' }, description: 'List of token identifiers in format chainId:address (e.g., ["1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"])' }, verified: { type: 'boolean', description: 'Filter for verified currencies only (recommended to avoid scam tokens)' }, limit: { type: 'number', minimum: 1, maximum: 100, description: 'Limit the number of results (default: 20, max: 100)' }, includeAllChains: { type: 'boolean', description: 'Include all chains for a currency when filtering by chainId and address' }, useExternalSearch: { type: 'boolean', description: 'Use 3rd party APIs to search for tokens not indexed by Relay' }, depositAddressOnly: { type: 'boolean', description: 'Return only currencies supported with deposit address bridging' } }, additionalProperties: false }, handler: handleGetCurrencies(client) } }; } - src/tools/currencies.ts:124-182 (schema)Tool definition including name 'relay_get_currencies', description, and inputSchema (JSON schema) defining all filter parameters (chainIds, term, address, verified, limit, etc.).
relay_get_currencies: { name: 'relay_get_currencies', description: 'Get currencies metadata from a curated list. Supports filtering by chain IDs, search terms, addresses, and other criteria.\n\nCommon Examples:\n• Find USDC on specific chains: {"chainIds": [1, 10, 8453], "term": "usdc", "verified": true, "limit": 10}\n• All major tokens on Ethereum: {"chainIds": [1], "defaultList": true, "limit": 20}\n• Search by contract address: {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "includeAllChains": true}\n• Verified tokens only: {"verified": true, "limit": 50}\n• Deposit-address supported tokens: {"depositAddressOnly": true}\n\nTip: Use verified=true to avoid scam/fake tokens. Use term to search by symbol/name.', inputSchema: { type: 'object', properties: { defaultList: { type: 'boolean', description: 'Return default currencies from curated list' }, chainIds: { type: 'array', items: { type: 'number' }, description: 'Chain IDs to search for currencies (e.g., [1, 10, 137] for Ethereum, Optimism, Polygon)' }, term: { type: 'string', description: 'Search term for currencies (symbol, name, or partial match)' }, address: { type: 'string', description: 'Token contract address to search for' }, currencyId: { type: 'string', description: 'Specific currency ID to retrieve' }, tokens: { type: 'array', items: { type: 'string' }, description: 'List of token identifiers in format chainId:address (e.g., ["1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"])' }, verified: { type: 'boolean', description: 'Filter for verified currencies only (recommended to avoid scam tokens)' }, limit: { type: 'number', minimum: 1, maximum: 100, description: 'Limit the number of results (default: 20, max: 100)' }, includeAllChains: { type: 'boolean', description: 'Include all chains for a currency when filtering by chainId and address' }, useExternalSearch: { type: 'boolean', description: 'Use 3rd party APIs to search for tokens not indexed by Relay' }, depositAddressOnly: { type: 'boolean', description: 'Return only currencies supported with deposit address bridging' } }, additionalProperties: false }, handler: handleGetCurrencies(client) } - src/tools/currencies.ts:42-54 (handler)The handleGetCurrencies function is the actual handler. It validates args with getCurrenciesSchema (Zod), then calls client.getCurrencies(validated) which POSTs to /currencies/v2 API endpoint.
function handleGetCurrencies(client: RelayClient) { return async (args: unknown) => { try { const validated = getCurrenciesSchema.parse(args); return await client.getCurrencies(validated); } catch (error) { if (error instanceof z.ZodError) { throw new Error(`Invalid arguments: ${error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`); } throw error; } }; } - src/tools/currencies.ts:18-30 (helper)Zod schema (getCurrenciesSchema) for validating the input arguments to relay_get_currencies before they reach the API.
const getCurrenciesSchema = z.object({ defaultList: z.boolean().optional(), chainIds: z.array(z.number()).optional(), term: z.string().optional(), address: z.string().optional(), currencyId: z.string().optional(), tokens: z.array(z.string()).optional(), verified: z.boolean().optional(), limit: z.number().min(1).max(100).optional(), includeAllChains: z.boolean().optional(), useExternalSearch: z.boolean().optional(), depositAddressOnly: z.boolean().optional(), }); - src/client/RelayClient.ts:378-381 (helper)The getCurrencies method on RelayClient that makes the actual HTTP POST request to /currencies/v2 endpoint.
async getCurrencies(request: CurrenciesV2Request = {}): Promise<CurrencyV2[]> { const response = await this.client.post<CurrencyV2[]>('/currencies/v2', request); return response.data; }