algorand-interaction

Interact with Algorand blockchain through the Algorand MCP server (126 tools across 16 categories, including x402 payments and Bazaar discovery).

Key Characteristics

• Agent wallet — the MCP server holds mnemonics in a local SQLite DB at ~/.algorand-mcp/wallet.db (file mode 0600) and signs transactions on your behalf via the wallet_* tools. Mnemonics are never returned in tool responses. The DB file IS the secret — protect the data directory like any secret material (relevant for Docker: mount ~/.algorand-mcp as a persistent volume).
• Multi-network — supports mainnet, testnet, and localnet

mcporter Syntax (Critical)

When calling Algorand MCP tools via mcporter, use the correct syntax:

Correct:

mcporter call algorand-mcp.tool_name --args '{"param": "value", "network": "testnet"}'

Also correct (flag-style):

mcporter call algorand-mcp.tool_name param=value network=testnet

Wrong — args not sent properly:

mcporter call algorand-mcp tool_name '{"param": "value"}'  # Space instead of dot, missing --args

Key points:

• Use server.tool (dot notation), NOT server tool (space)
• Use --args '{"json"}' for JSON payloads
• Or use param=value / param:value flag syntax

Session Start Checklist

At EVERY session start:

1. Check wallet: wallet_get_info with target network — verify an account exists and is active
2. If no accounts: Guide user to create one with wallet_add_account (sets nickname)
3. If needs funding: Generate ARC-26 QR with generate_algorand_qrcode or direct to testnet faucet: https://lora.algokit.io/testnet/fund
4. If needs USDC funding: Generate ARC-26 QR with generate_algorand_qrcode or direct to testnet faucet: https://faucet.circle.com/
5. Confirm network: Always confirm which network (mainnet, testnet, localnet) before transactions

Network Selection

Every tool that touches the blockchain accepts a network parameter:

| Value | Description | |-------|-------------| | testnet | Algorand testnet — default if omitted (algorand-mcp 4.2.5+), safe for development | | mainnet | Algorand mainnet — real value, exercise caution. Pass only when the user explicitly names mainnet | | localnet | Local dev network (requires ALGORAND_LOCALNET_URL env var) |

Mainnet is never implicit. If the user does not name a network, use testnet. Switch to mainnet only on an explicit user instruction, and confirm the full action (amount, asset, sender, receiver, network) before signing.

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

| Asset | ASA ID | Decimals | |-------|--------|----------| | ALGO | native | 6 | | USDC | 31566704 | 6 | | USDT | 312769 | 6 | | goETH | 386192725 | 8 | | goBTC | 386195940 | 8 |

Always verify asset IDs on-chain — scam tokens use similar names.

Amounts and Decimals

| Asset | Unit | 1 Whole Token = | |-------|------|-----------------| | ALGO | microAlgos | 1,000,000 | | USDC (ASA 31566704) | micro-units | 1,000,000 (6 decimals) | | Custom ASAs | base units | Depends on decimals field |

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)

| Step | Tool | Purpose | |------|------|---------| | 1 | wallet_get_info | Verify active account, check balance | | 2 | Query tools | Get blockchain data (account info, asset info, etc.) | | 3 | make_*_txn | Build the transaction | | 4 | wallet_sign_transaction | Sign with active wallet account | | 5 | send_raw_transaction | Submit signed transaction to network | | 6 | Present txID | Show transaction ID with explorer link (see below) |

Post-Transaction: Deliver Transaction ID

ALWAYS present the transaction ID to the user after any successful transaction submission. Use the correct explorer link based on the network:

| Network | Explorer Link Template | |---------|----------------------| | mainnet | https://allo.info/tx/{txId} | | testnet | https://lora.algokit.io/testnet/transaction/{txId} |

Example output after a testnet transaction:

Transaction confirmed! TXID123... View on explorer: https://lora.algokit.io/testnet/transaction/TXID123...

Example output after a mainnet transaction:

Transaction confirmed! TXID456... View on explorer: https://allo.info/tx/TXID456...

This applies to ALL transaction types: payments, asset transfers, opt-ins, app calls, atomic groups, and any other operation that yields a transaction ID.

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):

| Step | Tool | Purpose | |------|------|---------| | 1 | make_*_txn | Build the transaction | | 2 | sign_transaction | Sign with provided secret key hex | | 3 | send_raw_transaction | Submit signed transaction | | 4 | Present txID | Show transaction ID with explorer link |

Atomic Group Transaction Workflow

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

| Step | Tool | Purpose | |------|------|---------| | 1 | make_*_txn (multiple) | Build each transaction | | 2 | assign_group_id | Assign group ID to all transactions | | 3 | wallet_sign_transaction_group | Sign all transactions in group with wallet | | 4 | send_raw_transaction | Submit all signed transactions | | 5 | Present txIDs | Show all transaction IDs with explorer links |

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 Building (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_lookup_account_transactions, api_indexer_search_for_accounts, api_indexer_lookup_applications, api_indexer_lookup_application_logs, api_indexer_lookup_application_box, api_indexer_lookup_application_boxes, api_indexer_search_for_applications, 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_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 — DEX-aggregated swaps across Tinyman V2, Pact, Folks with optimal routing. See the haystack-router-interaction skill for detailed workflows and reference docs.

Pera Asset Verification (3): api_pera_asset_verification_status, api_pera_verified_asset_details, api_pera_verified_asset_search — mainnet asset verification (verified/trusted/suspicious/unverified), detailed asset info with USD value, and search by name/keyword

ARC-26 URI (1): generate_algorand_qrcode

Knowledge Base (1): get_knowledge_doc

x402 Payments (2): x402_discover_payment_requirements, make_http_request_with_x402 — probe an x402-protected endpoint for payment requirements, then pay-and-fetch in one call. See the x402 Payment Workflow section below for the supervised pattern.

x402 Bazaar Discovery (3): bazaar_list, bazaar_search, bazaar_get_resource_details — browse and search the Bazaar discovery directory hosted by the configured facilitator (facilitator.goplausible.xyz by default) to find paid resources cataloged across the x402 ecosystem before calling make_http_request_with_x402. See the x402 Bazaar Discovery section below for the recommended pattern.

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 Payments & Bazaar Discovery — load the dedicated skill

For paid HTTP resources (HTTP 402 responses), Bazaar discovery, and any workflow involving the five x402 tools (x402_discover_payment_requirements, make_http_request_with_x402, bazaar_list, bazaar_search, bazaar_get_resource_details), load the dedicated algorand-x402-payment skill. It covers:

• The three payment patterns (fire-and-forget, inspect-then-pay, Bazaar-then-pay)
• Tool argument cheatsheet for all five x402/Bazaar tools
• Mainnet-confirmation discipline and maxAmountPerRequest as a budget cap
• Common pitfalls (the paymentRequirements[N] must be an OBJECT schema failure, etc.)
• Wallet prerequisites (USDC opt-in, balance)
• Protocol-level reference (PaymentRequired V2 schema, fee-payer abstraction, CAIP-2 mapping, V1 vs V2 differences)

Trigger to load: any time you encounter an HTTP 402 response, the user mentions x402 / paid APIs / paid resources / Bazaar / "find me a paid X", or you need to call any of the five tools listed above.

Alpha Arcade Prediction Markets

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

| Step | Tool | Purpose | |------|------|---------| | 1 | wallet_get_info | Verify active account, check ALGO + USDC balance | | 2 | alpha_get_live_markets | Browse available markets | | 3 | alpha_get_orderbook | Check liquidity and prices for a market | | 4 | alpha_create_market_order or alpha_create_limit_order | Place an order | | 5 | alpha_get_positions / alpha_get_open_orders | Check portfolio |

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.

QR Code Display (ARC-26 URI)

generate_algorand_qrcode generates an Algorand payment URI and QR code per ARC-26 specification via QRClaw service.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | address | Yes | Receiver Algorand address | | label | No | Payment label | | amount | No | Amount in microunits (e.g. 1000000 = 1 ALGO or 1 USDC) | | asset | No | ASA ID for asset transfers; omit or 0 for ALGO | | note | No | Payment note | | xnote | No | Exclusive immutable note |

Returns:

• qr — UTF-8 text QR code (terminal-friendly)
• uri — the algorand:// URI string
• link — shareable hosted QR URL (via QRClaw service)
• expires_in — link validity period

Channel-Aware Output:

After calling generate_algorand_qrcode, tailor output to the channel:

TUI / Web channels (terminal, web UI, canvas):

1. UTF-8 QR block — paste the Unicode block characters from qr inside a code fence
2. URI string — the algorand:// URI for wallet deep links
3. Shareable link — the hosted QR URL from link

Example:

[paste UTF-8 QR here]

URI: algorand://... Shareable QR: [link URL]

Social channels (Telegram, Discord, WhatsApp, Signal, Slack, IRC, etc.):

• Skip the UTF-8 QR block — too bulky for chat
• Show only:
  • URI string — for wallet deep links
  • Shareable link — renders nicely in-app as a clickable QR image

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 and check verification tier with api_pera_asset_verification_status — 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 Documentation and Example code
• GoPlausible x402 Examples template Projects
• CAIP-2 Specification
• Coinbase x402 Protocol