MCP Tools Reference

This page documents all 14 tools exposed by the Starknet MCP Server (10 core + 4 conditional). Each tool includes its description, parameters, return values, and usage examples.

Tool Invocation

These tools are invoked automatically by your AI assistant. You describe what you want in natural language, and the AI selects the appropriate tool and parameters.

Quick Reference

Tool	Purpose	Write?
`starknet_get_balance`	Get single token balance	No
`starknet_get_balances`	Get multiple token balances	No
`starknet_transfer`	Transfer tokens	Yes
`starknet_swap`	Swap tokens via avnu	Yes
`starknet_get_quote`	Get swap quote	No
`starknet_call_contract`	Call view function	No
`starknet_invoke_contract`	Invoke contract function	Yes
`starknet_estimate_fee`	Estimate transaction fee	No
`starknet_build_calls`	Build unsigned calls for external signing	No
`x402_starknet_sign_payment_required`	Sign X-402 payment	No
`starknet_register_agent`	Register ERC-8004 identity	Yes
`starknet_set_agent_metadata`	Set agent metadata	Yes
`starknet_get_agent_metadata`	Read agent metadata	No
`starknet_deploy_agent_account`	Deploy agent account	Yes

starknet_get_balance

Get the token balance for an address on Starknet. Supports common token symbols (ETH, STRK, USDC, USDT) or any token contract address.

Parameters

Parameter	Type	Required	Description
`token`	string	Yes	Token symbol (`ETH`, `STRK`, `USDC`, `USDT`) or contract address
`address`	string	No	Address to check. Defaults to the configured account address

Returns

{
  "balance": "1.5",
  "raw": "1500000000000000000",
  "decimals": 18,
  "tokenAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
}

Field	Type	Description
`balance`	string	Human-readable balance (e.g., "1.5")
`raw`	string	Raw balance in smallest unit (wei)
`decimals`	number	Token decimal places
`tokenAddress`	string	Normalized token contract address

Examples

Error Codes

Error	Cause	Recovery
`INVALID_TOKEN`	Token symbol or address not recognized	Use a valid token symbol or contract address
`INVALID_ADDRESS`	Address format incorrect	Ensure address starts with `0x`
`RPC_ERROR`	Network communication failed	Check RPC URL and network connectivity

starknet_get_balances

Get multiple token balances in a single optimized call. More efficient than calling starknet_get_balance multiple times.

Parameters

Parameter	Type	Required	Description
`tokens`	string[]	Yes	Array of token symbols or addresses (max 200)
`address`	string	No	Address to check. Defaults to configured account

Returns

{
  "balances": [
    {
      "token": "ETH",
      "balance": "0.5",
      "raw": "500000000000000000",
      "decimals": 18,
      "tokenAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
    },
    {
      "token": "STRK",
      "balance": "1234.56",
      "raw": "1234560000000000000000",
      "decimals": 18,
      "tokenAddress": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d"
    }
  ],
  "method": "balance_checker"
}

Field	Type	Description
`balances`	array	Array of balance objects
`method`	string	`"balance_checker"` (optimized) or `"batch_rpc"` (fallback)

The server uses a BalanceChecker contract (0x031ce64a666fbf9a2b1b2ca51c2af60d9a76d3b85e5fbfb9d5a8dbd3fedc9716) to fetch multiple balances in a single RPC call. If the contract is unavailable, it falls back to parallel individual RPC calls.

Examples

Error Codes

Error	Cause	Recovery
`TOO_MANY_TOKENS`	More than 200 tokens requested	Split into multiple calls
`INVALID_TOKEN`	One or more tokens not recognized	Check token symbols/addresses

starknet_transfer

Transfer tokens to another address on Starknet. Supports gasfree mode with two options: sponsored (dApp pays gas) or token-based (pay gas in ERC-20).

Parameters

Parameter	Type	Required	Description
`recipient`	string	Yes	Recipient address (must start with `0x`)
`token`	string	Yes	Token symbol or contract address
`amount`	string	Yes	Amount in human-readable format (e.g., "1.5")
`gasfree`	boolean	No	Enable gasfree mode (default: `false`)
`gasToken`	string	No	Token to pay gas in (only used when gasfree=true without API key)

Gasfree Modes

Sponsored mode: When AVNU_PAYMASTER_API_KEY is set, the dApp pays all gas fees.

Token mode: Without an API key, gas is paid in the specified gasToken (or the token being transferred).

Returns

{
  "success": true,
  "transactionHash": "0x7f3a2bc1...",
  "recipient": "0x04f3e8d17b41...",
  "token": "USDC",
  "amount": "100",
  "gasfree": false
}

Field	Type	Description
`success`	boolean	Whether the transaction succeeded
`transactionHash`	string	Transaction hash on Starknet
`recipient`	string	Recipient address
`token`	string	Token transferred
`amount`	string	Amount transferred
`gasfree`	boolean	Whether gasfree mode was used

Examples

Error Codes

Error	Cause	Recovery
`INSUFFICIENT_BALANCE`	Not enough tokens to transfer	Check balance and reduce amount
`INSUFFICIENT_GAS`	Not enough tokens for gas fees	Add gas token or enable gasfree
`INVALID_RECIPIENT`	Recipient address invalid	Verify the address format
`TRANSACTION_REVERTED`	On-chain execution failed	Check recipient can receive tokens

Double-check addresses

Token transfers are irreversible. Always verify the recipient address before confirming a transfer.

starknet_swap

Execute a token swap on Starknet using the avnu aggregator for best prices across all DEXes. Supports gasfree mode.

Parameters

Parameter	Type	Required	Description
`sellToken`	string	Yes	Token to sell (symbol or address)
`buyToken`	string	Yes	Token to buy (symbol or address)
`amount`	string	Yes	Amount to sell in human-readable format
`slippage`	number	No	Max slippage as decimal (0.01 = 1%, default: 0.01)
`gasfree`	boolean	No	Enable gasfree mode (default: `false`)
`gasToken`	string	No	Token to pay gas in (gasfree only, defaults to sellToken)

Returns

{
  "success": true,
  "transactionHash": "0x2bc1a7f3...",
  "sellToken": "USDC",
  "buyToken": "ETH",
  "sellAmount": "100",
  "buyAmount": "0.0284",
  "priceImpact": "0.12",
  "gasFeesUsd": "0.05",
  "gasfree": false,
  "routes": [
    {
      "name": "JediSwap",
      "percent": 100
    }
  ]
}

Field	Type	Description
`success`	boolean	Whether the swap succeeded
`transactionHash`	string	Transaction hash
`sellToken`	string	Token sold
`buyToken`	string	Token received
`sellAmount`	string	Amount sold
`buyAmount`	string	Amount received
`priceImpact`	string	Price impact percentage
`gasFeesUsd`	string	Gas fees in USD
`gasfree`	boolean	Whether gasfree mode was used
`routes`	array	DEX routing information

Examples

Error Codes

Error	Cause	Recovery
`NO_ROUTES_FOUND`	No DEX path between tokens	Try different token pair or smaller amount
`INSUFFICIENT_LIQUIDITY`	Not enough liquidity for swap size	Reduce swap amount
`SLIPPAGE_EXCEEDED`	Price moved beyond slippage tolerance	Increase slippage or retry
`INSUFFICIENT_BALANCE`	Not enough sell token	Check balance
`PRICE_IMPACT_TOO_HIGH`	Swap would cause significant price impact	Reduce amount or split into multiple swaps

starknet_get_quote

Get a swap quote without executing the trade. Useful for comparing prices or displaying expected outcomes before confirmation.

Parameters

Parameter	Type	Required	Description
`sellToken`	string	Yes	Token to sell (symbol or address)
`buyToken`	string	Yes	Token to buy (symbol or address)
`amount`	string	Yes	Amount to sell

Returns

{
  "sellToken": "USDC",
  "buyToken": "ETH",
  "sellAmount": "100",
  "buyAmount": "0.0284",
  "priceImpact": "0.12",
  "gasFeesUsd": "0.05",
  "quoteId": "abc123...",
  "routes": [
    {
      "name": "JediSwap",
      "address": "0x...",
      "percent": 60
    },
    {
      "name": "10KSwap",
      "address": "0x...",
      "percent": 40
    }
  ]
}

Field	Type	Description
`sellToken`	string	Token being sold
`buyToken`	string	Token being bought
`sellAmount`	string	Input amount
`buyAmount`	string	Expected output amount
`priceImpact`	string	Price impact percentage
`gasFeesUsd`	string	Estimated gas fees in USD
`quoteId`	string	Quote identifier (for reference)
`routes`	array	DEX routing breakdown

Examples

Error Codes

Error	Cause	Recovery
`NO_ROUTES_FOUND`	No DEX path available	Try different tokens
`INVALID_TOKEN`	Token not recognized	Use valid symbol or address

starknet_call_contract

Call a read-only (view) function on a Starknet smart contract. Does not create a transaction or cost gas.

Parameters

Parameter	Type	Required	Description
`contractAddress`	string	Yes	Contract address (0x-prefixed hex)
`entrypoint`	string	Yes	Function name to call
`calldata`	string[]	No	Function arguments as strings (default: `[]`, max 256 items)

Input Validation

Each calldata item is validated as a 251-bit felt (field element)
Decimal values are automatically converted to 0x-prefixed hex
Contract addresses are normalized and validated

Returns

{
  "result": ["0x4574686572", "0x455448"],
  "contractAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  "entrypoint": "name"
}

Field	Type	Description
`result`	string[]	Array of return values as hex strings
`contractAddress`	string	Contract that was called
`entrypoint`	string	Function that was called

Examples

Error Codes

Error	Cause	Recovery
`ENTRYPOINT_NOT_FOUND`	Function doesn't exist	Check function name spelling
`INVALID_CALLDATA`	Wrong number or type of arguments	Verify function signature
`CALLDATA_TOO_LARGE`	More than 256 calldata items	Split into multiple calls
`INVALID_FELT`	Calldata value exceeds 251 bits	Use smaller values or split uint256
`CONTRACT_NOT_FOUND`	No contract at address	Verify contract address

starknet_invoke_contract

Execute a state-changing function on a Starknet smart contract. Creates a transaction that modifies blockchain state.

Parameters

Parameter	Type	Required	Description
`contractAddress`	string	Yes	Contract address (0x-prefixed hex)
`entrypoint`	string	Yes	Function name to call
`calldata`	string[]	No	Function arguments as strings (default: `[]`, max 256 items)
`gasfree`	boolean	No	Enable gasfree mode (default: `false`)
`gasToken`	string	No	Token to pay gas in (gasfree only)

Input Validation

Each calldata item is validated as a 251-bit felt (field element)
Decimal values are automatically converted to 0x-prefixed hex
Contract addresses are normalized and validated

Returns

{
  "success": true,
  "transactionHash": "0x3a7c1b2d...",
  "contractAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  "entrypoint": "approve",
  "gasfree": false
}

Field	Type	Description
`success`	boolean	Whether the transaction succeeded
`transactionHash`	string	Transaction hash
`contractAddress`	string	Contract that was invoked
`entrypoint`	string	Function that was called
`gasfree`	boolean	Whether gasfree mode was used

Examples

Error Codes

Error	Cause	Recovery
`TRANSACTION_REVERTED`	Contract execution failed	Check function requirements
`INSUFFICIENT_GAS`	Not enough for gas fees	Add gas tokens or use gasfree
`ENTRYPOINT_NOT_FOUND`	Function doesn't exist	Verify function name
`INVALID_CALLDATA`	Wrong arguments	Check function signature

State Changes

Unlike starknet_call_contract, this tool modifies blockchain state. Ensure you understand what the function does before invoking.

starknet_estimate_fee

Estimate the transaction fee for a contract call before executing it.

Parameters

Parameter	Type	Required	Description
`contractAddress`	string	Yes	Contract address
`entrypoint`	string	Yes	Function name
`calldata`	string[]	No	Function arguments (default: `[]`)

Returns

{
  "overallFee": "0.000042",
  "resourceBounds": {
    "l1_gas": {
      "max_amount": "0x1a4",
      "max_price_per_unit": "0x5af3107a4000"
    },
    "l2_gas": {
      "max_amount": "0x0",
      "max_price_per_unit": "0x0"
    }
  },
  "unit": "STRK"
}

Field	Type	Description
`overallFee`	string	Estimated fee in human-readable format
`resourceBounds`	object	L1 and L2 gas bounds
`unit`	string	Fee currency (STRK for V3 transactions)

Examples

Error Codes

Error	Cause	Recovery
`ESTIMATION_FAILED`	Transaction would fail	Check function and calldata
`INVALID_CALLDATA`	Wrong arguments	Verify function signature

starknet_build_calls

Build unsigned Starknet calls without executing them. Returns validated Call[] objects compatible with starknet.js and external signers like Cartridge Controller, hardware wallets, or multisig contracts.

Parameters

Parameter	Type	Required	Description
`calls`	object[]	Yes	Array of call objects (max 256 calls)

Each call object has:

Field	Type	Required	Description
`contractAddress`	string	Yes	Contract address (0x-prefixed hex)
`entrypoint`	string	Yes	Function name to call
`calldata`	string[]	No	Function arguments as strings (default: `[]`)

No Execution

This tool performs validation only — it does not execute transactions or require gas. Use it to build calls for external signing workflows.

Returns

{
  "calls": [
    {
      "contractAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
      "entrypoint": "transfer",
      "calldata": ["0x04f3e8d17b41...", "0x5f5e100", "0x0"]
    }
  ],
  "count": 1,
  "validated": true
}

Field	Type	Description
`calls`	array	Validated Call[] objects ready for signing
`count`	number	Number of calls in the batch
`validated`	boolean	Whether all calls passed validation

Examples

Error Codes

Error	Cause	Recovery
`EMPTY_CALLS`	Empty calls array provided	Provide at least one call
`TOO_MANY_CALLS`	More than 256 calls	Split into multiple batches
`INVALID_ADDRESS`	Contract address format invalid	Use 0x-prefixed hex address
`INVALID_ENTRYPOINT`	Entrypoint name empty	Provide a valid function name
`INVALID_FELT`	Calldata value exceeds 251 bits	Use smaller values or split uint256

x402_starknet_sign_payment_required

Sign a base64-encoded PAYMENT-REQUIRED header containing Starknet typedData. Part of the X-402 payment protocol for AI-to-AI micropayments.

Parameters

Parameter	Type	Required	Description
`paymentRequiredHeader`	string	Yes	Base64-encoded JSON from PAYMENT-REQUIRED HTTP header
`rpcUrl`	string	No	Starknet RPC URL (defaults to env var)
`accountAddress`	string	No	Account address (defaults to env var)
`privateKey`	string	No	Private key (defaults to env var)

Returns

{
  "paymentSignatureHeader": "eyJzaWduYXR1cmUiOiIweDEyMzQ...",
  "payload": {
    "version": "1",
    "network": "starknet-mainnet",
    "amount": "1000000",
    "token": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
    "recipient": "0x04f3..."
  }
}

Field	Type	Description
`paymentSignatureHeader`	string	Base64-encoded signature for PAYMENT-SIGNATURE header
`payload`	object	Decoded payment request details

Examples

Error Codes

Error	Cause	Recovery
`INVALID_HEADER`	Malformed base64 or JSON	Check header encoding
`UNSUPPORTED_NETWORK`	Network not Starknet	Verify payment request
`SIGNATURE_FAILED`	Signing operation failed	Check private key

X-402 Protocol

X-402 enables HTTP-based micropayments where servers return 402 Payment Required responses. The client signs and returns a PAYMENT-SIGNATURE header to authorize payment.

starknet_register_agent

Register a new ERC-8004 agent identity in the IdentityRegistry. This is a conditional tool that only appears when ERC8004_IDENTITY_REGISTRY_ADDRESS is configured.

Conditional Tool

This tool requires the ERC8004_IDENTITY_REGISTRY_ADDRESS environment variable to be set. If not configured, the tool is not exposed.

Parameters

Parameter	Type	Required	Description
`token_uri`	string	No	Metadata URI (IPFS, Arweave, data URI). If omitted, registers without metadata
`gasfree`	boolean	No	Enable sponsored gasfree mode (default: `false`)

Returns

{
  "success": true,
  "transactionHash": "0x7f3a2bc1...",
  "identityRegistryAddress": "0x05e4f6a7b8c9d0...",
  "agentId": "42"
}

Field	Type	Description
`success`	boolean	Whether the registration succeeded
`transactionHash`	string	Transaction hash
`identityRegistryAddress`	string	IdentityRegistry address used
`agentId`	string	ERC-8004 agent ID (identity NFT token ID)

Examples

Error Codes

Error	Cause	Recovery
`REGISTRY_NOT_CONFIGURED`	`ERC8004_IDENTITY_REGISTRY_ADDRESS` not set	Configure the environment variable
`REGISTRATION_FAILED`	Registry transaction reverted	Check deployer has sufficient funds
`EVENT_NOT_FOUND`	Registered event missing	Check transaction on explorer

starknet_set_agent_metadata

Set on-chain metadata for an ERC-8004 agent identity. This is a conditional tool that only appears when ERC8004_IDENTITY_REGISTRY_ADDRESS is configured.

Conditional Tool

This tool requires the ERC8004_IDENTITY_REGISTRY_ADDRESS environment variable to be set. If not configured, the tool is not exposed.

Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (u256 as decimal or hex string)
`key`	string	Yes	Metadata key (non-empty string)
`value`	string	Yes	Metadata value (any string)
`gasfree`	boolean	No	Enable sponsored gasfree mode (default: `false`)

Standard Metadata Keys

The ERC-8004 spec defines these standard keys:

agentName - Human-readable agent name
agentType - Agent type/category
version - Agent version string
model - AI model identifier
status - Operational status
framework - Agent framework used
capabilities - JSON array of capabilities
a2aEndpoint - Agent-to-Agent protocol endpoint
moltbookId - MoltBook identifier

The key agentWallet is reserved and cannot be set via this tool.

Returns

{
  "success": true,
  "transactionHash": "0x7f3a2bc1...",
  "identityRegistryAddress": "0x05e4f6a7b8c9d0...",
  "agentId": "42",
  "key": "agentName",
  "value": "Trading Bot Alpha"
}

Field	Type	Description
`success`	boolean	Whether the transaction succeeded
`transactionHash`	string	Transaction hash
`identityRegistryAddress`	string	IdentityRegistry address used
`agentId`	string	Agent ID that was updated
`key`	string	Metadata key that was set
`value`	string	Value that was stored

Examples

Error Codes

Error	Cause	Recovery
`REGISTRY_NOT_CONFIGURED`	`ERC8004_IDENTITY_REGISTRY_ADDRESS` not set	Configure the environment variable
`EMPTY_KEY`	Key is empty string	Provide a non-empty key
`RESERVED_KEY`	Attempted to set `agentWallet`	Use a different key (agentWallet is system-managed)
`NOT_OWNER`	Caller is not owner/approved for agent_id	Use the owner account or get approval
`TRANSACTION_REVERTED`	Contract execution failed	Check agent_id exists and you have permission

starknet_get_agent_metadata

Read on-chain metadata for an ERC-8004 agent identity. This is a read-only operation that does not create a transaction.

Conditional Tool

This tool requires the ERC8004_IDENTITY_REGISTRY_ADDRESS environment variable to be set. If not configured, the tool is not exposed.

Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (u256 as decimal or hex string)
`key`	string	Yes	Metadata key to read (non-empty string)

Returns

{
  "agentId": "42",
  "key": "agentName",
  "value": "Trading Bot Alpha",
  "identityRegistryAddress": "0x05e4f6a7b8c9d0..."
}

Field	Type	Description
`agentId`	string	Agent ID queried
`key`	string	Metadata key requested
`value`	string	Decoded value (empty string if not set)
`identityRegistryAddress`	string	IdentityRegistry address used

Examples

Error Codes

Error	Cause	Recovery
`REGISTRY_NOT_CONFIGURED`	`ERC8004_IDENTITY_REGISTRY_ADDRESS` not set	Configure the environment variable
`EMPTY_KEY`	Key is empty string	Provide a non-empty key
`RPC_ERROR`	Network communication failed	Check RPC URL and connectivity

starknet_deploy_agent_account

Deploy a new agent account via the AgentAccountFactory with ERC-8004 identity binding. This is a conditional tool that only appears when AGENT_ACCOUNT_FACTORY_ADDRESS is configured.

Conditional Tool

This tool requires the AGENT_ACCOUNT_FACTORY_ADDRESS environment variable to be set. If not configured, the tool is not exposed.

Parameters

Parameter	Type	Required	Description
`public_key`	string	Yes	Stark public key (felt, 0x-prefixed, non-zero, max 251 bits)
`token_uri`	string	Yes	Token URI for agent identity metadata (IPFS, Arweave, etc.)
`salt`	string	No	Deploy salt (felt, max 251 bits). Random if omitted for deterministic addresses
`gasfree`	boolean	No	Enable sponsored gasfree mode (default: `false`)

Input Validation

public_key must be a non-zero value within the 251-bit felt range
salt must also fit within 251 bits if provided
Random salts are securely generated when not specified

Returns

{
  "success": true,
  "transactionHash": "0x7f3a2bc1...",
  "factoryAddress": "0x358301e1c530a6...",
  "publicKey": "0x04a7b3c8d9e1f2...",
  "salt": "0x1234567890abcdef...",
  "deployedAccountAddress": "0x05e4f6a7b8c9d0...",
  "agentId": "42"
}

Field	Type	Description
`success`	boolean	Whether the deployment succeeded
`transactionHash`	string	Transaction hash
`factoryAddress`	string	AgentAccountFactory address used
`publicKey`	string	Public key of the deployed account
`salt`	string	Salt used for address derivation
`deployedAccountAddress`	string	Address of the new agent account
`agentId`	string	ERC-8004 agent ID (identity NFT token ID)

Examples

Error Codes

Error	Cause	Recovery
`FACTORY_NOT_CONFIGURED`	`AGENT_ACCOUNT_FACTORY_ADDRESS` not set	Configure the environment variable
`INVALID_PUBLIC_KEY`	Public key format invalid	Use 0x-prefixed hex felt
`DEPLOYMENT_FAILED`	Factory transaction reverted	Check deployer has sufficient funds
`EVENT_NOT_FOUND`	AccountDeployed event missing	Check transaction on explorer

Token Addresses

The MCP server recognizes these token symbols:

Symbol	Address	Decimals
`ETH`	`0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7`	18
`STRK`	`0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d`	18
`USDC`	`0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8`	6
`USDT`	`0x068f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8`	6

Additional tokens are resolved dynamically via the avnu token list with 24-hour caching.

Error Handling

All tools return structured errors with:

{
  "error": "INSUFFICIENT_BALANCE",
  "message": "Not enough USDC to complete transfer. Required: 100, Available: 50",
  "suggestion": "Check your balance and try a smaller amount"
}

Field	Description
`error`	Error code for programmatic handling
`message`	Human-readable description
`suggestion`	Recovery action when available

Common error patterns are translated to user-friendly messages with actionable guidance.