| name | starknet-wallet |
| description | Create and manage Starknet wallets for AI agents. Transfer tokens, check balances, manage session keys, deploy accounts, and interact with smart contracts using native Account Abstraction. |
| license | Apache-2.0 |
| metadata | {"author":"starknet-agentic","version":"1.0.0","org":"keep-starknet-strange"} |
| keywords | ["starknet","wallet","transfer","balance","session-keys","account-abstraction","paymaster","gasless","agent-wallet","strk","eth"] |
| allowed-tools | ["Bash","Read","Write","Glob","Grep","Task"] |
| user-invocable | true |
Starknet Wallet Skill
Manage Starknet wallets for AI agents with native Account Abstraction support.
When to Use
- Creating, funding, and operating Starknet accounts for agent workflows.
- Checking balances, sending transfers, managing session keys, or invoking contracts from an agent wallet.
When NOT to Use
- DeFi-specific routing, staking, or lending flows better covered by
starknet-defi.
- Cairo contract authoring, deployment-only operations, or security auditing.
Quick Start
- Install the SDK dependencies and set Starknet RPC/account environment variables.
- Use skills catalog to pivot to adjacent modules like DeFi, deployment, or auditing.
Prerequisites
npm install starknet@^8.9.1 @avnu/avnu-sdk@^4.0.1
Environment variables:
STARKNET_RPC_URL=https://starknet-mainnet.g.alchemy.com/v2/YOUR_KEY
STARKNET_ACCOUNT_ADDRESS=0x...
STARKNET_PRIVATE_KEY=0x...
AVNU_BASE_URL=https://starknet.api.avnu.fi (optional)
AVNU_PAYMASTER_URL=https://starknet.paymaster.avnu.fi (optional)
AVNU_PAYMASTER_API_KEY=your_key (optional, for free gas)
Available MCP Tools
The Starknet MCP Server provides these tools for wallet operations:
| Tool | Purpose | Key Features |
|---|
starknet_get_balance | Check single token balance | Simple, fast queries |
starknet_get_balances | Check multiple token balances | Batch queries (up to 200 tokens), single RPC call |
starknet_transfer | Send tokens | Supports gasless mode (paymaster) |
starknet_call_contract | Read contract state | Call view functions |
starknet_invoke_contract | Execute contract functions | Write operations, supports gasless |
starknet_swap | Execute token swaps | AVNU integration, best price routing |
starknet_get_quote | Get swap quotes | Price estimation before swap |
starknet_register_agent | Register agent identity | ERC-8004 on-chain identity |
Balance Tools Detail
starknet_get_balance (Single Token)
Query balance for one token. Use for simple cases.
Input:
token (required): Token symbol (ETH, STRK, USDC, USDT) or contract address
address (optional): Wallet address (defaults to agent's address)
Response:
{
"address": "0x...",
"token": "ETH",
"tokenAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
"balance": "1.5",
"raw": "1500000000000000000",
"decimals": 18
}
starknet_get_balances (Multiple Tokens)
Query balances for multiple tokens in a single RPC call. More efficient for portfolio views.
Input:
tokens (required): Array of token symbols or addresses (max 200)
address (optional): Wallet address
Response:
{
"address": "0x...",
"balances": [
{ "token": "ETH", "tokenAddress": "0x...", "balance": "1.5", "raw": "...", "decimals": 18 },
{ "token": "USDC", "tokenAddress": "0x...", "balance": "100", "raw": "...", "decimals": 6 }
],
"tokensQueried": 2,
"method": "balance_checker"
}
When to use:
- starknet_get_balance: Quick single-token check
- starknet_get_balances: Portfolio overview, multi-token operations
Core Operations
Check Balance (Single Token)
Use the starknet_get_balance MCP tool for simple single-token queries:
const result = await mcpClient.callTool({
name: "starknet_get_balance",
arguments: {
address: "0x...",
token: "ETH",
}
});
Direct starknet.js usage:
import { RpcProvider, Contract } from "starknet";
const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC_URL });
const ethAddress = "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
const ethContract = new Contract({
abi: erc20Abi,
address: ethAddress,
providerOrAccount: provider,
});
const balance = await ethContract.balanceOf(accountAddress);
const balanceBigInt = BigInt(balance.low) + (BigInt(balance.high) << 128n);
Check Multiple Balances (Batch)
Use starknet_get_balances for efficient multi-token queries (single RPC call):
const result = await mcpClient.callTool({
name: "starknet_get_balances",
arguments: {
address: "0x...",
tokens: ["ETH", "STRK", "USDC", "USDT"],
}
});
Direct starknet.js usage with BalanceChecker contract:
import { RpcProvider, Contract } from "starknet";
const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC_URL });
const BALANCE_CHECKER_ADDRESS = "0x031ce64a666fbf9a2b1b2ca51c2af60d9a76d3b85e5fbfb9d5a8dbd3fedc9716";
const BALANCE_CHECKER_ABI = [
{
type: "struct",
name: "core::integer::u256",
members: [
{ name: "low", type: "core::integer::u128" },
{ name: "high", type: "core::integer::u128" },
],
},
{
type: "struct",
name: "governance::balance_checker::NonZeroBalance",
members: [
{ name: "token", type: "core::starknet::contract_address::ContractAddress" },
{ name: "balance", type: "core::integer::u256" },
],
},
{
type: "function",
name: "get_balances",
inputs: [
{ name: "address", type: "core::starknet::contract_address::ContractAddress" },
{ name: "tokens", type: "core::array::Span::<core::starknet::contract_address::ContractAddress>" },
],
outputs: [{ type: "core::array::Span::<governance::balance_checker::NonZeroBalance>" }],
state_mutability: "view",
},
];
const balanceChecker = new Contract({
abi: BALANCE_CHECKER_ABI,
address: BALANCE_CHECKER_ADDRESS,
providerOrAccount: provider,
});
const tokens = [
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
"0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
"0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
];
const result = await balanceChecker.get_balances(accountAddress, tokens);
for (const item of result) {
const tokenAddr = "0x" + BigInt(item.token).toString(16).padStart(64, "0");
const balance = BigInt(item.balance);
console.log(`${tokenAddr}: ${balance}`);
}
When to use which:
starknet_get_balance: Single token, simple use case
starknet_get_balances: Multiple tokens, portfolio view, more efficient
Transfer Tokens
Use the starknet_transfer MCP tool with optional gasless mode:
const result = await mcpClient.callTool({
name: "starknet_transfer",
arguments: {
recipient: "0x...",
token: "STRK",
amount: "10.5",
gasfree: false,
}
});
Gasless Transfer (Pay gas in token instead of ETH/STRK):
const result = await mcpClient.callTool({
name: "starknet_transfer",
arguments: {
recipient: "0x...",
token: "STRK",
amount: "100",
gasfree: true,
gasToken: "USDC",
}
});
Direct starknet.js usage:
import { Account, RpcProvider, CallData, cairo, ETransactionVersion } from "starknet";
const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC_URL });
const account = new Account({
provider,
address: process.env.STARKNET_ACCOUNT_ADDRESS,
signer: process.env.STARKNET_PRIVATE_KEY,
transactionVersion: ETransactionVersion.V3,
});
const tokenAddress = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";
const { transaction_hash } = await account.execute({
contractAddress: tokenAddress,
entrypoint: "transfer",
calldata: CallData.compile({
recipient: recipientAddress,
amount: cairo.uint256(amountInWei),
}),
});
await account.waitForTransaction(transaction_hash);
Estimate Fees
const estimatedFee = await account.estimateInvokeFee({
contractAddress: tokenAddress,
entrypoint: "transfer",
calldata: CallData.compile({
recipient: recipientAddress,
amount: cairo.uint256(amountInWei),
}),
});
Contract Interactions
Read contract state (view functions):
const result = await mcpClient.callTool({
name: "starknet_call_contract",
arguments: {
contractAddress: "0x...",
entrypoint: "balanceOf",
calldata: [accountAddress],
}
});
Write to contracts (state-changing functions):
const result = await mcpClient.callTool({
name: "starknet_invoke_contract",
arguments: {
contractAddress: "0x...",
entrypoint: "approve",
calldata: [spenderAddress, ...uint256Amount],
gasfree: true,
gasToken: "USDC",
}
});
Multi-Call (Batch Transactions)
const { transaction_hash } = await account.execute([
{
contractAddress: tokenA,
entrypoint: "approve",
calldata: CallData.compile({
spender: routerAddress,
amount: cairo.uint256(amount),
}),
},
{
contractAddress: routerAddress,
entrypoint: "swap",
calldata: CallData.compile({ }),
},
]);
Gasless Transfer (Pay Gas in Token) - SDK v4 + PaymasterRpc
import { getQuotes, executeSwap } from "@avnu/avnu-sdk";
import { PaymasterRpc } from "starknet";
const paymaster = new PaymasterRpc({
nodeUrl: process.env.AVNU_PAYMASTER_URL || "https://starknet.paymaster.avnu.fi",
});
const result = await executeSwap({
provider: account,
quote: bestQuote,
slippage: 0.01,
executeApprove: true,
paymaster: {
active: true,
provider: paymaster,
params: {
feeMode: {
mode: "default",
gasToken: usdcAddress,
},
},
},
});
Token Resolution
The MCP server uses TokenService to resolve token symbols and addresses. Static tokens (ETH, STRK, USDC, USDT) are always available. For other tokens, the service fetches metadata from avnu SDK.
import { fetchTokenByAddress, fetchVerifiedTokenBySymbol } from '@avnu/avnu-sdk';
const lords = await fetchVerifiedTokenBySymbol('LORDS');
console.log(lords.address, lords.decimals);
const token = await fetchTokenByAddress('0x...');
console.log(token.symbol, token.name, token.decimals);
import { fetchTokens } from '@avnu/avnu-sdk';
const page = await fetchTokens({ tags: ['Verified'], size: 100 });
page.content.forEach(t => console.log(t.symbol, t.address));
Static tokens available without network calls: ETH, STRK, USDC, USDT
Session Keys (Agent Autonomy)
Session keys allow agents to execute pre-approved transactions without per-action human approval:
- Human owner creates a session key with policies:
- Allowed contract addresses and methods
- Maximum spending per transaction/period
- Expiry timestamp
- Agent uses the session key for autonomous operations
- Owner can revoke at any time
Reference implementation: Cartridge Controller
Configuration
| Variable | Purpose | Default |
|---|
STARKNET_RPC_URL | Starknet JSON-RPC endpoint | Required |
STARKNET_ACCOUNT_ADDRESS | Agent's account address | Required |
STARKNET_PRIVATE_KEY | Agent's signing key | Required |
AVNU_BASE_URL | avnu API base URL | https://starknet.api.avnu.fi |
AVNU_PAYMASTER_URL | avnu paymaster URL | https://starknet.paymaster.avnu.fi |
Error Handling
| Error | Cause | Resolution |
|---|
INSUFFICIENT_BALANCE | Not enough tokens | Check balance before transfer |
INVALID_NONCE | Nonce mismatch | Retry with fresh nonce |
TRANSACTION_REVERTED | Contract execution failed | Check calldata and allowances |
FEE_TRANSFER_FAILURE | Can't pay gas fee | Use paymaster or add ETH/STRK |
References