> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlayer.network/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tools Reference
> Complete guide to all available Token Layer MCP tools
## Overview
The Token Layer MCP server provides specialized tools that enable AI assistants to interact with tokens and blockchain operations. Each tool is optimized for specific tasks and includes built-in validation and error handling.
All tools require authentication via Bearer token (API key) or OAuth 2.0 flow.
***
## Token Operations
### create\_token
Deploy a new token or meme coin on blockchain with custom branding.
**Capabilities:**
* Create tokens on Base or Base Sepolia networks
* Custom name, symbol, and description
* Upload logo, banner, and promotional video
* Add social media links (Twitter, Discord, Telegram, YouTube, Website)
* Tag with hashtags for discovery
* Optional auto-execution (one-step deployment)
**Parameters:**
* `name` (required): Token name (e.g., "Doge Coin", "Rocket Token")
* `symbol` (required): 2-10 character ticker (e.g., "DOGE", "REKT")
* `description` (required): Token description and story
* `image` (required): Logo URL or file path (PNG, JPEG, GIF, WEBP, SVG)
* `chainSlug` (required): "base" or "base-sepolia"
* `banner` (optional): Banner image URL or path
* `video` (optional): Promotional video URL or path
* `links` (optional): Object with social media URLs
* `tags` (optional): Array of hashtags
* `autoExecute` (optional): Auto-deploy on-chain (default: false)
* `userAddress` (optional): Custom wallet address
**Example:**
```typescript theme={null}
{
name: "Rocket Dog",
symbol: "RDOG",
description: "The fastest dog in crypto, heading to the moon!",
image: "https://example.com/rocket-dog.png",
chainSlug: "base-sepolia",
links: {
twitter: "https://twitter.com/rocketdog",
website: "https://rocketdog.com"
},
tags: ["meme", "dog", "moon"],
autoExecute: true
}
```
**Response:**
```json theme={null}
{
"success": true,
"tokenId": "uuid-here",
"contractAddress": "0x742d35Cc...",
"transactionHash": "0x9f3b2c..."
}
```
***
### get\_tokens
Browse and discover tokens with filtering and sorting options.
**Capabilities:**
* Filter by trending, new, popular, or top posts
* Search by hashtag/category
* Pagination support
* Filter verified tokens only
* Get holder counts, vote data, and creator info
**Parameters:**
* `filter` (required): "trending" | "new" | "popular" | "top\_posts"
* `limit` (optional): Max results (1-100, default: 20)
* `offset` (optional): Pagination offset (default: 0)
* `hashtag_name` (optional): Filter by hashtag
* `verified_only` (optional): Only verified tokens (default: false)
**Example:**
```typescript theme={null}
{
filter: "trending",
limit: 10,
hashtag_name: "defi"
}
```
**Response:**
```json theme={null}
{
"tokens": [
{
"id": "uuid",
"name": "DeFi Token",
"symbol": "DEFI",
"contract_address": "0x...",
"holders_count": 1250,
"upvote_count": 450,
"downvote_count": 12,
"creator": {...}
}
],
"total": 156
}
```
***
### search\_token
Find a specific token by address, slug, or name.
**Capabilities:**
* Search by contract address (0x...)
* Search by URL-friendly slug
* Partial name matching
* Returns full token details including price and market cap
**Parameters:**
* `input` (required): Contract address, slug, or partial name
**Example:**
```typescript theme={null}
{
input: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
// or
{
input: "rocket-dog"
}
// or
{
input: "doge"
}
```
**Response:**
```json theme={null}
{
"id": "uuid",
"name": "Rocket Dog",
"symbol": "RDOG",
"contract_address": "0x742d35Cc...",
"price_usd": "0.0042",
"market_cap": "420000",
"description": "The fastest dog in crypto...",
"image_url": "https://...",
"holders_count": 350
}
```
***
### trade\_token
Buy or sell tokens with automatic execution.
**Capabilities:**
* Buy with exact USD input or exact token output
* Sell with exact token input or exact USD output
* Auto-switches between RobinSwap (new tokens) and UniswapV3 (graduated)
* Optional auto-execution
* Slippage protection
**Parameters:**
* `tokenId` (required): UUID of token to trade
* `chainSlug` (required): "base" or "base-sepolia"
* `direction` (required): "buy" | "sell"
* `buyAmountUSD` (optional): USD to spend when buying
* `buyAmountToken` (optional): Token amount to receive when buying
* `sellAmountToken` (optional): Token amount to sell
* `sellAmountUSD` (optional): USD to receive when selling
* `autoExecute` (optional): Execute immediately (default: false)
* `userAddress` (optional): Custom wallet address
**Example - Buy:**
```typescript theme={null}
{
tokenId: "uuid-here",
chainSlug: "base",
direction: "buy",
buyAmountUSD: 100, // Spend $100
autoExecute: true
}
```
**Example - Sell:**
```typescript theme={null}
{
tokenId: "uuid-here",
chainSlug: "base",
direction: "sell",
sellAmountToken: 1000, // Sell 1000 tokens
autoExecute: true
}
```
**Response:**
```json theme={null}
{
"success": true,
"transactionHash": "0x9f3b2c...",
"inputAmount": "100",
"outputAmount": "23809.52",
"protocol": "RobinSwap"
}
```
***
### quote\_trade\_token
Get a price quote without executing a trade.
**Capabilities:**
* Preview trade amounts before execution
* No gas fees (quote only)
* Real-time pricing
* Shows which protocol will be used
**Parameters:**
* `tokenId` (required): UUID of token
* `chainSlug` (required): "base" or "base-sepolia"
* `direction` (optional): "buy" | "sell" (default: "sell")
* `amount` (optional): Amount to quote (default: 1)
* `inputToken` (optional): "token" | "usdc" (default: "token")
**Example:**
```typescript theme={null}
{
tokenId: "uuid-here",
chainSlug: "base",
direction: "buy",
amount: 100,
inputToken: "usdc" // How many tokens for $100?
}
```
**Response:**
```json theme={null}
{
"inputAmount": "100",
"outputAmount": "23809.52",
"protocol": "RobinSwap",
"isGraduated": false,
"timestamp": "2025-11-04T22:30:00Z"
}
```
***
## Blockchain Operations
### execute\_transaction
Execute blockchain transactions on-chain.
**Capabilities:**
* Send transactions with custom data
* Automatic gas fee calculation
* Support for Base and Base Sepolia
* Required for deploying tokens (after create\_token)
**Parameters:**
* `to` (required): Recipient address (0x...)
* `amount` (required): Amount in wei (as string)
* `chainSlug` (required): "base" | "base-sepolia"
* `data` (optional): Transaction data (hex string)
**Example:**
```typescript theme={null}
{
to: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
amount: "1000000000000000000", // 1 ETH in wei
chainSlug: "base",
data: "0x..."
}
```
**Response:**
```json theme={null}
{
"transactionHash": "0x9f3b2c...",
"success": true
}
```
This tool executes real blockchain transactions. Always verify transaction details before confirming!
***
## Tool Combinations
AI assistants can chain multiple tools together for complex workflows:
### Example: Research → Buy Flow
```
1. search_token("rocket dog")
2. quote_trade_token(...) // Check price
3. trade_token(..., autoExecute: true) // Execute buy
```
### Example: Create → Trade Flow
```
1. create_token(..., autoExecute: true)
2. get_tokens(filter: "new") // Verify token appears
3. quote_trade_token(...) // Get initial price
```
### Example: Price Comparison
```
1. get_tokens(filter: "trending")
2. Loop through each token
3. quote_trade_token(...) for each to compare prices
```
***
## Error Handling
All MCP tools return standardized error responses:
```json theme={null}
{
"error": "Error message",
"code": "ERROR_CODE",
"details": {...}
}
```
**Common Error Codes:**
* `AUTHENTICATION_FAILED` - Invalid API key or OAuth token
* `INSUFFICIENT_BALANCE` - Not enough funds for transaction
* `INVALID_PARAMETERS` - Missing or invalid parameters
* `NETWORK_ERROR` - Blockchain network issues
* `RATE_LIMIT_EXCEEDED` - Too many requests
* `TOKEN_NOT_FOUND` - Token doesn't exist
* `TRANSACTION_FAILED` - On-chain transaction reverted
***
## Rate Limits
* **Anonymous**: 10 requests/minute
* **Authenticated**: 100 requests/minute
* **Premium**: 1000 requests/minute
The MCP server automatically handles rate limiting and will queue requests when necessary.
***
## Best Practices
Use `quote_trade_token` before `trade_token` to preview amounts and avoid surprises.
Set `autoExecute: false` when learning. Only use `autoExecute: true` when you understand the action.
Use Base Sepolia for testing token creation and trading before mainnet.
Provide as much context as possible when searching tokens (symbol, name, or address).
Always use `taggedCoinId` when posting about tokens to increase visibility.
Specify `voting_token_id` to give your votes more weight based on holdings.
***
## Next Steps
Get inspired with ready-to-use examples
Explore the underlying REST API
Set up your first MCP connection
Get help from our team