Algorand Interaction

Algorand MCP Interaction

Interact with Algorand blockchain through the Algorand MCP server (126 tools across 15 categories).

Key Characteristics

• Agent-wallet signing — use wallet_* tools to sign; the MCP server holds the mnemonics in a local SQLite DB and signs on your behalf. Mnemonics are never returned in tool responses.
• Multi-network — supports mainnet, testnet, and localnet

Calling MCP Tools

MCP tools are deferred — you MUST use ToolSearch to load them before calling:

ToolSearch("+algorand wallet")                                    # Search by keyword — loads matching tools
ToolSearch("select:mcp__algorand-mcp__wallet_get_info")           # Load a specific tool by full name

Once loaded, call them normally:

mcp__algorand-mcp__wallet_get_info { "network": "testnet" }
mcp__algorand-mcp__make_payment_txn { "from": "ADDR", "to": "ADDR", "amount": 1000000, "network": "testnet" }

Full tool name pattern: mcp__algorand-mcp__<tool_name>. If you get "tool not found", use ToolSearch("+algorand <keyword>") to load it first.

Session Start Checklist

At EVERY session start:

1. Load tools first: Call ToolSearch("+algorand wallet") to load wallet tools — MCP tools are deferred and MUST be loaded via ToolSearch before use
2. Check wallet: mcp__algorand-mcp__wallet_get_info with target network — verify an account exists and is active
3. If no accounts: Guide user to create one with wallet_add_account (load via ToolSearch first)
4. If needs funding: Generate ARC-26 QR with generate_algorand_qrcode — returns { qr, uri, link, expires_in }. Display the qr text block and shareable link. Or direct to testnet faucet: https://lora.algokit.io/testnet/fund
5. If needs USDC funding: Generate ARC-26 QR with generate_algorand_qrcode — returns { qr, uri, link, expires_in }. Display the qr text block and shareable link. Or direct to testnet faucet: https://faucet.circle.com/
6. Confirm network: Always confirm which network (mainnet, testnet, localnet) before transactions
7. Load additional tools as needed: Use ToolSearch("+algorand <keyword>") to load tools for the task at hand

Network Selection

Every tool that touches the blockchain accepts a network parameter:

Default to testnet during development.

Pre-Transaction Validation

Before ANY transaction:

1. MBR Check: Account needs 0.1 ALGO base + 0.1 per asset/app opt-in
2. Asset Opt-In: Verify with api_algod_get_account_asset_info before ASA transfers
3. Fees: Every txn costs 0.001 ALGO (1,000 microAlgos) minimum
4. Balance Check: Fetch current balance with wallet_get_info or api_algod_get_account_info
5. Order: Fund account with ALGO first, then asset transactions

Common Mainnet Assets

Always verify asset IDs on-chain — scam tokens use similar names. Use api_pera_asset_verification_status to check verification tier before transacting unknown assets.

Amounts and Decimals

Always check asset's decimals field with api_algod_get_asset_by_id before computing amounts.

Transaction Types

• pay: ALGO transfers → make_payment_txn
• axfer: Asset transfers, opt-in, clawback → make_asset_transfer_txn
• acfg: Asset create/configure/destroy → make_asset_create_txn, make_asset_config_txn, make_asset_destroy_txn
• afrz: Asset freeze/unfreeze → make_asset_freeze_txn
• appl: Smart contract calls → make_app_create_txn, make_app_call_txn, make_app_update_txn, make_app_delete_txn, make_app_optin_txn, make_app_closeout_txn, make_app_clear_txn
• keyreg: Consensus key registration → make_keyreg_txn

Wallet Transaction Workflow (Recommended)

One-Step Asset Opt-In

For asset opt-ins, use the shortcut:

wallet_optin_asset { assetId: 31566704, network: "testnet" }

External Key Transaction Workflow

When the user provides their own secret key (not using the wallet):

Atomic Group Transaction Workflow

For atomic (all-or-nothing) multi-transaction groups:

Best-Price Swap via Haystack Router (DEX Aggregator)

Haystack Router aggregates quotes across multiple Algorand DEXes (Tinyman, Pact, Folks) and LST protocols (tALGO, xALGO) to find the optimal swap route.

CRITICAL — Swap direction (type parameter):

• "Buy 10 ALGO" → user wants exactly 10 ALGO out → type: "fixed-output", amount = 10000000
• "Sell/swap 10 ALGO" → user spends exactly 10 ALGO → type: "fixed-input", amount = 10000000
• "Buy USDC for 10 ALGO" → user spends exactly 10 ALGO → type: "fixed-input", amount = 10000000
• Rule: "buy X of Y" = fixed-output. "sell/swap/use X of Y" = fixed-input. If ambiguous, ask.

For detailed Haystack Router workflows (batch swaps, configuration, slippage guidance), load the haystack-router-interaction skill. For building swap UIs or integrating the @txnlab/haystack-router SDK, load the haystack-router-development skill.

Alpha Arcade Prediction Markets

Trade on-chain prediction markets (YES/NO outcomes) denominated in USDC via the Alpha Arcade integration (14 tools).

All prices and quantities use microunits (1,000,000 = $1.00 or 1 share). Orders require both ALGO (~0.957 per escrow) and USDC collateral.

For detailed Alpha Arcade workflows (orderbook mechanics, multi-choice markets, split/merge shares, claiming, collateral model), load the alpha-arcade-interaction skill.

Tool Categories

Wallet (10): wallet_add_account, wallet_remove_account, wallet_list_accounts, wallet_switch_account, wallet_get_info, wallet_get_assets, wallet_sign_transaction, wallet_sign_transaction_group, wallet_sign_data, wallet_optin_asset

Account (8): create_account, rekey_account, mnemonic_to_mdk, mdk_to_mnemonic, secret_key_to_mnemonic, mnemonic_to_secret_key, seed_from_mnemonic, mnemonic_from_seed

Utility (13): ping, validate_address, encode_address, decode_address, get_application_address, bytes_to_bigint, bigint_to_bytes, encode_uint64, decode_uint64, verify_bytes, sign_bytes, encode_obj, decode_obj

Transaction (18): make_payment_txn, make_keyreg_txn, make_asset_create_txn, make_asset_config_txn, make_asset_destroy_txn, make_asset_freeze_txn, make_asset_transfer_txn, make_app_create_txn, make_app_update_txn, make_app_delete_txn, make_app_optin_txn, make_app_closeout_txn, make_app_clear_txn, make_app_call_txn, assign_group_id, sign_transaction, encode_unsigned_transaction, decode_signed_transaction

Algod (5): compile_teal, disassemble_teal, send_raw_transaction, simulate_raw_transactions, simulate_transactions

Algod API (13): api_algod_get_account_info, api_algod_get_account_application_info, api_algod_get_account_asset_info, api_algod_get_application_by_id, api_algod_get_application_box, api_algod_get_application_boxes, api_algod_get_asset_by_id, api_algod_get_pending_transaction, api_algod_get_pending_transactions_by_address, api_algod_get_pending_transactions, api_algod_get_transaction_params, api_algod_get_node_status, api_algod_get_node_status_after_block

Indexer API (17): api_indexer_lookup_account_by_id, api_indexer_lookup_account_assets, api_indexer_lookup_account_app_local_states, api_indexer_lookup_account_created_applications, api_indexer_search_for_accounts, api_indexer_lookup_applications, api_indexer_lookup_application_logs, api_indexer_search_for_applications, api_indexer_lookup_application_box, api_indexer_lookup_application_boxes, api_indexer_lookup_asset_by_id, api_indexer_lookup_asset_balances, api_indexer_lookup_asset_transactions, api_indexer_search_for_assets, api_indexer_lookup_transaction_by_id, api_indexer_lookup_account_transactions, api_indexer_search_for_transactions

NFDomains (6): api_nfd_get_nfd, api_nfd_get_nfds_for_addresses, api_nfd_get_nfd_activity, api_nfd_get_nfd_analytics, api_nfd_browse_nfds, api_nfd_search_nfds

Tinyman DEX (9): api_tinyman_get_pool, api_tinyman_get_pool_analytics, api_tinyman_get_pool_creation_quote, api_tinyman_get_liquidity_quote, api_tinyman_get_remove_liquidity_quote, api_tinyman_get_swap_quote, api_tinyman_get_asset_optin_quote, api_tinyman_get_validator_optin_quote, api_tinyman_get_validator_optout_quote

Haystack Router (3): api_haystack_get_swap_quote, api_haystack_execute_swap, api_haystack_needs_optin

Pera Asset Verification (3): api_pera_asset_verification_status, api_pera_verified_asset_details, api_pera_verified_asset_search

Alpha Arcade (14): alpha_get_live_markets, alpha_get_reward_markets, alpha_get_market, alpha_get_orderbook, alpha_get_open_orders, alpha_get_positions, alpha_create_limit_order, alpha_create_market_order, alpha_cancel_order, alpha_amend_order, alpha_propose_match, alpha_split_shares, alpha_merge_shares, alpha_claim

x402 HTTP Payments (5): x402_discover_payment_requirements, make_http_request_with_x402, bazaar_list, bazaar_search, bazaar_get_resource_details — Coinbase Wallet MCP-compatible x402 payment tools plus Bazaar discovery directory queries against facilitator.goplausible.xyz

ARC-26 URI (1): generate_algorand_qrcode

Knowledge Base (1): get_knowledge_doc

Pagination

API responses are paginated. All API tools accept optional itemsPerPage (default 10) and pageToken parameters. Pass pageToken from a previous response to fetch the next page.

x402 Payment Workflow

Use the two algorand-mcp x402 tools to access x402-protected HTTP resources — the MCP tools handle transaction construction, signing, base64 encoding, and PAYMENT-SIGNATURE assembly internally. You only orchestrate the discover → select → pay flow.

Recommended supervised pattern (default)

1. Probe the endpoint to read what it costs:

   x402_discover_payment_requirements {
     baseURL: "https://example.x402.goplausible.xyz",
     path: "/avm/weather",
     method: "GET"
   }
   

2. Inspect the returned accepts[] array. Pick the entry you'll pay with — usually the cheapest Algorand entry on the network you want, within budget. On mainnet, confirm the cost with the user before continuing.

3. Pay and fetch in one call, passing the pre-fetched requirements back so the tool doesn't re-probe:

   make_http_request_with_x402 {
     baseURL: "https://example.x402.goplausible.xyz",
     path: "/avm/weather",
     method: "GET",
     paymentRequirements: <accepts[] from step 1>,
     preferredNetwork: "testnet",
     maxAmountPerRequest: 10000
   }
   

Faster unsupervised pattern (testnet, known endpoints)

Skip step 1. Call make_http_request_with_x402 { baseURL, path, method } — it discovers, selects the cheapest affordable Algorand requirement, builds the atomic group, signs the payment leg with the active wallet, retries, and returns the resource. Always pass maxAmountPerRequest as a guardrail; pass preferredNetwork to pin testnet/mainnet.

Bazaar discovery (find paid resources to call)

Three tools query the facilitator's directory of cataloged paid resources:

• bazaar_list { network?, method?, merchantId?, limit?, offset?, full? } — browse cataloged resources. Compact summary per item by default (URL, description, Algorand-payable accepts, popularity counters); pass full: true for verbatim records including discoveryInfo.
• bazaar_search { query, limit?, network?, includeTestnets?, scheme?, maxUsdPrice?, asset?, payTo?, extensions? } — keyword search with budget and asset filters.
• bazaar_get_resource_details { resource } — fetch a single resource by exact URL.

Then feed the chosen accepts[] (or the resourceUrl) into make_http_request_with_x402.

Always

• Mainnet = real money — confirm cost with the user before mainnet payments. Use maxAmountPerRequest as a budget cap.
• Amounts are in atomic units. USDC has 6 decimals: 1,000,000 atomic units = $1.00.
• preferredNetwork accepts mainnet | testnet | localnet; if omitted, the selector picks the cheapest affordable Algorand entry regardless of which Algorand network it's on.
• paymentRequirements is an ARRAY OF OBJECTS — preferredNetwork and maxAmountPerRequest are TOP-LEVEL siblings, not array members. The schema rejects malformed inputs with a specific message.

For reference examples and common error reactions, see references/examples-algorand-mcp.md.

References

For detailed tool documentation:

• Tool Reference: See references/algorand-mcp.md

For workflow examples (including x402 payment):

• Examples: See references/examples-algorand-mcp.md

NFD Important Note

When using NFD (.algo names), always use the depositAccount field from the NFD response for transactions, NOT other address fields.

Security

• Mainnet = real value — always confirm with user before mainnet transactions
• Never log, display, or store mnemonics or secret keys — use wallet_* tools for signing
• Verify recipient addresses with validate_address — transactions are irreversible
• Verify asset IDs on-chain — scam tokens use similar names

Links

• GoPlausible: https://goplausible.com
• Algorand: https://algorand.co
• Algorand x402: https://x402.goplausible.xyz
• Algorand x402 test endpoints: https://example.x402.goplausible.xyz/
• Algorand x402 Facilitator: https://facilitator.goplausible.xyz
• Testnet Faucet: https://lora.algokit.io/testnet/fund
• Testnet USDC Faucet: https://faucet.circle.com/
• Algorand Developer Docs: https://dev.algorand.co/
• Algorand Developer Docs Github : https://github.com/algorandfoundation/devportal
• Algorand Developer Examples Github : https://github.com/algorandfoundation/devportal-code-examples
• GoPlausible x402-avm Documentation and Example code
• GoPlausible x402-avm Examples template Projects
• CAIP-2 Specification
• Coinbase x402 Protocol