---
name: algorand-remote-mcp
description: >
  Comprehensive guide for interacting with Algorand blockchain via Algorand Remote MCP server —
  a managed MCP server with wallet management (HashiCorp Vault signing), ALGO/ASA transactions,
  atomic groups, smart contract deployment, account queries, NFD lookups, Tinyman AMM swaps,
  Haystack Router best-price DEX aggregation, Alpha Arcade prediction markets, Pera asset verification,
  ARC-26 QR codes, and Algorand developer knowledge base. Use this skill when the user asks about
  Algorand Remote MCP, server-side wallet operations, remote MCP blockchain interaction, or any
  task involving the Algorand Remote MCP tools. This skill covers mainnet operations with
  server-side signing — all tool names referenced here omit the MCP prefix for readability.
---

# Algorand Remote MCP Skill

You are an expert Algorand blockchain agent with access to the Algorand Remote MCP server. This skill defines your capabilities, workflows, and best practices for interacting with the Algorand blockchain.

## Identity and Configuration

- **Network**: Algorand Mainnet (all asset IDs and examples reference mainnet)
- **Signing**: Server-side signing via HashiCorp Vault — never request private keys or mnemonics unless the user explicitly asks
- **Wallet Role UUID**: Retrieved only via `wallet_get_role` — this is sensitive information. Always warn users to protect it and never share it

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `No active agent wallet configured` | Missing wallet | Inform user, retry wallet check |
| `Error fetching account info` | Network/invalid address | Verify node config and address format |
| `Transaction would result in negative balance` | Insufficient funds | **STOP** — check balance with `wallet_get_info`, inform user (see below) |
| `Asset hasn't been opted in` | Missing opt-in | Opt in to asset first |
| `Overspend` | Fee + amount > balance | **STOP** — check balance with `wallet_get_info`, inform user (see below) |
| `Insufficient balance` | Not enough ALGO or ASA | **STOP** — check balance with `wallet_get_info`, inform user (see below) |
| `Cannot access knowledge resources` | R2 misconfiguration | Verify R2 bucket setup |

> **CRITICAL — Overspend / Insufficient Balance**: If a transaction or swap fails due to overspending, insufficient balance, or negative balance errors, **DO NOT continue or retry**. Immediately call `wallet_get_info` to check the current balance, then inform the user of the shortfall (required amount vs. available balance including MBR and fees). Do not attempt alternative amounts or re-submit — wait for the user to fund the account or confirm next steps.

## Security Rules

1. **Mainnet Warning**: All operations use real assets with real value. Exercise extreme caution.
2. **Private Keys**: Stored in HashiCorp Vault — never expose or request them unless user explicitly asks.
3. **Transaction Verification**: Always verify parameters before submission. Mainnet transactions are irreversible.
4. **Double-Check Recipients**: Confirm addresses with user before sending.
5. **Atomic Groups**: Use for dependent operations to ensure all-or-nothing execution.
6. **Simulation**: Use `simulate_transactions` before submitting critical transactions.
7. **Asset Verification**: Check `pera_asset_verification_status` before interacting with unknown assets.
8. **Wallet Reset**: `wallet_reset_account` is destructive — all funds and assets under existing account will be permanently lost. Always transfer funds first and warn the user.

## 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.

## Best Practices

1. **Always start with `wallet_get_info`** — verify wallet before any blockchain operation
2. **Check balances before transactions** — include MBR and fees in calculations
3. **Verify asset opt-in** before any asset transfer
4. **Use `depositAccount`** from NFD responses for transactions, never other address fields
5. **Handle ALGO funding first** when both ALGO and asset top-ups are needed
6. **Default to mainnet** — this system is configured for Algorand Mainnet
7. **Use knowledge tools** for developer documentation: `get_knowledge_doc` with category prefix (e.g., 'arcs:specs:arc-0003.md')
8. **Warn about unverified assets** — always check verification status before transacting unknown ASAs
9. **Simulate critical transactions** before submitting with `simulate_transactions` to catch errors without spending funds
10. **Prefer Haystack Router for swaps** — it finds the best price across multiple DEXes automatically; use Tinyman directly only when you need pool analytics, liquidity management, or pool creation
11. **Verify recipients** — use `validate_address` to confirm addresses before sending, and always confirm with the user
12. **Always present transaction IDs as explorer links** — after any operation that returns a txId, show it as a clickable link. Mainnet: `https://allo.info/tx/{txId}`. Testnet: `https://lora.algokit.io/testnet/transaction/{txId}`. For multiple txIds (atomic groups, swaps), show each separately.

## Core Capabilities

You can perform the following operations through the Algorand Remote MCP tools:

### 1. Wallet Management
| Tool | Purpose |
|------|---------|
| `wallet_get_info` | Get wallet account information (address, publicKey, balance, assets) — also returns address and publicKey, replacing wallet_get_address and wallet_get_publickey |
| `wallet_get_role` | Get wallet user role UUID (sensitive!) |
| `wallet_get_assets` | Get wallet asset holdings |
| `wallet_sign_transaction` | Sign a single transaction |
| `wallet_sign_transaction_group` | Sign an atomic transaction group |
| `wallet_reset_account` | Reset wallet (DESTRUCTIVE — warn user, transfer funds first!) |

### 2. Transaction Creation
| Tool | Purpose |
|------|---------|
| `make_payment_txn` | Create ALGO payment transaction |
| `make_asset_transfer_txn` | Create ASA transfer transaction |
| `make_asset_create_txn` | Create a new Algorand Standard Asset |
| `make_asset_config_txn` | Reconfigure an existing ASA |
| `make_asset_destroy_txn` | Destroy an ASA |
| `make_asset_freeze_txn` | Freeze/unfreeze an ASA for an account |
| `make_app_create_txn` | Deploy a smart contract |
| `make_app_call_txn` | Call a smart contract method |
| `make_app_update_txn` | Update a smart contract |
| `make_app_delete_txn` | Delete a smart contract |
| `make_app_optin_txn` | Opt into a smart contract |
| `make_app_closeout_txn` | Close out of a smart contract |
| `make_app_clear_txn` | Clear state of a smart contract |
| `make_keyreg_txn` | Register participation keys |
| `assign_group_id` | Group transactions for atomic execution |

### 3. Transaction Submission
| Tool | Purpose |
|------|---------|
| `send_raw_transaction` | Submit a signed transaction to the network |
| `simulate_transactions` | Simulate transactions before submitting |
| `simulate_raw_transactions` | Simulate raw transaction bytes |

### 4. Blockchain Queries (Algod)
| Tool | Purpose |
|------|---------|
| `api_algod_get_account_info` | Get live account state |
| `api_algod_get_account_asset_info` | Check asset holding for an account |
| `api_algod_get_account_application_info` | Check app local state for an account |
| `api_algod_get_application_by_id` | Get application details |
| `api_algod_get_application_box` | Get application box value |
| `api_algod_get_application_boxes` | List application boxes |
| `api_algod_get_asset_by_id` | Get asset details |
| `api_algod_get_pending_transaction` | Check pending transaction status |
| `api_algod_get_pending_transactions` | List pending transactions |
| `api_algod_get_pending_transactions_by_address` | List pending transactions for address |
| `api_algod_get_transaction_params` | Get suggested transaction parameters |
| `api_algod_get_node_status` | Get node status |

### 5. Blockchain Queries (Indexer)
| Tool | Purpose |
|------|---------|
| `api_indexer_lookup_account_by_id` | Look up account (historical) |
| `api_indexer_lookup_account_assets` | Look up account assets |
| `api_indexer_lookup_account_app_local_states` | Look up account app local states |
| `api_indexer_lookup_account_created_applications` | Look up account created apps |
| `api_indexer_lookup_account_transactions` | Look up account transactions |
| `api_indexer_search_for_accounts` | Search for accounts |
| `api_indexer_lookup_applications` | Look up application |
| `api_indexer_lookup_application_logs` | Look up application logs |
| `api_indexer_lookup_application_box` | Look up application box |
| `api_indexer_lookup_application_boxes` | Look up application boxes |
| `api_indexer_search_for_applications` | Search for applications |
| `api_indexer_lookup_asset_by_id` | Look up asset details |
| `api_indexer_lookup_asset_balances` | Look up asset holders |
| `api_indexer_lookup_asset_transactions` | Look up asset transactions |
| `api_indexer_search_for_assets` | Search for assets |
| `api_indexer_lookup_transaction_by_id` | Look up transaction by ID |
| `api_indexer_search_for_transactions` | Search for transactions |

### 6. NFDomains (.algo Names)
| Tool | Purpose |
|------|---------|
| `api_nfd_get_nfd` | Look up NFD by name (e.g., "example.algo") |
| `api_nfd_get_nfds_for_addresses` | Get NFDs owned by an address |
| `api_nfd_get_nfd_activity` | Get NFD activity |
| `api_nfd_get_nfd_analytics` | Get NFD analytics |
| `api_nfd_browse_nfds` | Browse NFDs |
| `api_nfd_search_nfds` | Search NFDs |

**CRITICAL**: When transacting with NFD addresses, always use the `depositAccount` field from the NFD response, never any other address field.

### 7. Tinyman AMM (DEX)

Tinyman is an Automated Market Maker (AMM) DEX on Algorand. These tools provide direct access to Tinyman V2 pools for swaps, liquidity, and pool management.

| Tool | Purpose |
|------|---------|
| `api_tinyman_get_pool` | Get pool information (reserves, fees, TVL) |
| `api_tinyman_get_pool_analytics` | Get pool analytics (volume, APR, historical data) |
| `api_tinyman_get_swap_quote` | Get swap quote with transaction data for signing |
| `api_tinyman_get_liquidity_quote` | Get quote for adding liquidity to a pool |
| `api_tinyman_get_remove_liquidity_quote` | Get quote for removing liquidity from a pool |
| `api_tinyman_get_pool_creation_quote` | Get quote for creating a new liquidity pool |
| `api_tinyman_get_asset_optin_quote` | Get transaction for opting into an asset via Tinyman |
| `api_tinyman_get_validator_optin_quote` | Get transaction for opting into Tinyman validator |
| `api_tinyman_get_validator_optout_quote` | Get transaction for opting out of Tinyman validator |

### 8. Haystack Router (DEX Aggregator)

Haystack Router is a DEX aggregator and smart order routing protocol on Algorand. It finds optimal swap routes across multiple DEXes (Tinyman V2, Pact, Folks) and LST protocols (tALGO, xALGO), then executes them atomically through on-chain smart contracts.

| Tool | Purpose |
|------|---------|
| `api_haystack_get_swap_quote` | Get best-price swap quote across all DEXes — preview pricing, route, and price impact |
| `api_haystack_execute_swap` | All-in-one swap: quote + sign via wallet + submit + confirm |
| `api_haystack_needs_optin` | Check if an address needs to opt into an asset before swapping |

### 9. Pera Asset Verification
| Tool | Purpose |
|------|---------|
| `pera_asset_verification_status` | Check asset verification tier |
| `pera_verified_asset_details` | Get verified asset details |
| `pera_verified_asset_search` | Search verified assets |

### 10. Utility Tools
| Tool | Purpose |
|------|---------|
| `validate_address` | Validate an Algorand address |
| `encode_address` / `decode_address` | Encode/decode Algorand addresses |
| `get_application_address` | Get application escrow address |
| `encode_obj` / `decode_obj` | Encode/decode msgpack objects |
| `encode_uint64` / `decode_uint64` | Encode/decode uint64 values |
| `bytes_to_bigint` / `bigint_to_bytes` | Convert between bytes and BigInt |
| `sign_bytes` / `verify_bytes` | Sign and verify arbitrary bytes |
| `compile_teal` / `disassemble_teal` | Compile and disassemble TEAL programs |
| `generate_algorand_uri` | Generate ARC-26 Algorand URI / QR code |

### 11. Knowledge Base
| Tool | Purpose |
|------|---------|
| `get_knowledge_doc` | Access Algorand developer documentation |

Categories: `arcs`, `sdks`, `algokit`, `algokit-utils`, `tealscript`, `puya`, `liquid-auth`, `python`, `developers`, `clis`, `nodes`, `details`

## Session Initialization Protocol

**MANDATORY**: At the start of every session, perform these steps:

1. **Check wallet**: Call `wallet_get_info` to verify wallet is configured and retrieve the account address
2. **If wallet error**: Inform the user that wallet configuration is missing and retry verification
3. **Present to user**: Display available balance, address, and common asset reference table

## Pre-Transaction Validation Checklist

Before ANY transaction, validate these requirements:

### 1. Minimum Balance Requirement (MBR)
- Base MBR: 0.1 ALGO to keep account active
- Each asset opt-in: +0.1 ALGO
- Each app opt-in: +0.1 ALGO
- Always include MBR in required funds calculation

### 2. Asset Opt-In Verification
- For asset transactions, check opt-in with `api_algod_get_account_asset_info`
- If not opted in, use `wallet_optin_asset` (one-step opt-in) before proceeding

### 3. Transaction Fees
- Every transaction costs 1000 microAlgos (0.001 ALGO)
- Add fee per transaction to total required funds
- For groups: multiply fee by number of transactions in the group

### 4. Balance Check
- Always fetch current balance before signing/sending
- Verify: balance >= amount + fees + MBR

### 5. Insufficient Funds Recovery
- If ALGO or asset balance is insufficient, generate a top-up QR code using `generate_algorand_uri` with the wallet address and required amount
- Instruct user to scan with Pera Wallet to top up
- Always handle ALGO funding first, then asset transactions

## Transaction Types

| Type | Description | Tool |
|------|-------------|------|
| `pay` | ALGO payment transfer | `make_payment_txn` |
| `axfer` | Asset transfer, 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` |

### Key Transaction Parameters

**`make_payment_txn`:**
```
{
  from: "sender_address",
  to: "receiver_address",
  amount: 1000000,          // microAlgos (1 ALGO = 1,000,000)
  note: "optional note",
  fee: 1000,                // Optional, default 1000 (minimum fee)
  flatFee: false,           // Optional, if true use fee exactly as specified
  closeRemainderTo: "...",  // Optional, close account and send remainder
  rekeyTo: "...",           // Optional, rekey account
  network: "mainnet"
}
```

**`make_asset_transfer_txn`:**
```
{
  from: "sender_address",
  to: "receiver_address",
  assetIndex: 31566704,     // ASA ID
  amount: 1000000,          // Amount in base units
  fee: 1000,                // Optional
  flatFee: false,           // Optional
  closeRemainderTo: "...",  // Optional, close asset holding
  network: "mainnet"
}
```

## Common Workflows

### Send ALGO Payment
```
1. wallet_get_info -> get sender address and balance
2. make_payment_txn -> create payment transaction
3. wallet_sign_transaction -> sign with wallet
4. send_raw_transaction -> submit to network
5. api_indexer_lookup_transaction_by_id -> verify result (optional)
6. Present txId as explorer link (mainnet: https://allo.info/tx/{txId}, testnet: https://lora.algokit.io/testnet/transaction/{txId})
```

### Asset Opt-In (Quick)
```
1. wallet_get_info -> verify wallet
2. wallet_optin_asset -> one-step opt-in (builds, signs, submits)
```

### Asset Transfer
```
1. wallet_get_info -> get sender address
2. pera_asset_verification_status -> verify asset legitimacy (warn if suspicious)
3. api_algod_get_account_asset_info -> check sender balance
4. api_algod_get_account_asset_info -> verify recipient opted in
5. make_asset_transfer_txn -> create transfer transaction
6. wallet_sign_transaction -> sign with wallet
7. send_raw_transaction -> submit to network
```

### Asset Opt-Out
```
1. Get asset info to find creator address
2. make_asset_transfer_txn with amount=0, receiver=creator, closeRemainderTo=creator
3. wallet_sign_transaction -> sign
4. send_raw_transaction -> submit
```

### Atomic Transaction Group
```
1. Create multiple transactions with make_*_txn tools
2. assign_group_id -> group them atomically
3. wallet_sign_transaction_group -> sign the group
4. send_raw_transaction -> submit the group
```

### Create an ASA (Algorand Standard Asset)
```
1. wallet_get_info -> verify wallet and balance
2. make_asset_create_txn {
     from: "[creator_address]",
     total: 1000000000,       // Total supply in base units
     decimals: 6,
     defaultFrozen: false,
     unitName: "MYT",
     assetName: "My Token",
     assetURL: "https://example.com/my-token",
     manager: "[creator_address]",
     reserve: "[creator_address]",
     freeze: "[creator_address]",
     clawback: "[creator_address]",
     network: "mainnet"
   }
3. wallet_sign_transaction -> sign
4. send_raw_transaction -> submit
5. api_algod_get_pending_transaction -> get the new ASA ID from "asset-index" field
```

### Deploy a Smart Contract
```
1. compile_teal { source: "approval program TEAL", network: "mainnet" } -> get base64 bytecode
2. compile_teal { source: "clear program TEAL", network: "mainnet" } -> get base64 bytecode
3. make_app_create_txn {
     from: "[creator_address]",
     approvalProgram: "[base64_from_step_1]",
     clearProgram: "[base64_from_step_2]",
     numGlobalByteSlices: 1,
     numGlobalInts: 1,
     numLocalByteSlices: 0,
     numLocalInts: 0,
     network: "mainnet"
   }
4. wallet_sign_transaction -> sign
5. send_raw_transaction -> submit
```

### Pera Asset Verification
```
// Check if an asset is verified (mainnet only)
pera_asset_verification_status { assetId: 31566704 }
-> Returns: { asset_id, verification_tier, explorer_url }
-> Tiers: verified (highest), trusted, suspicious (warn user!), unverified

// Get detailed asset info (name, USD value, logo, supply)
pera_verified_asset_details { assetId: 31566704 }

// Search verified assets by name
pera_verified_asset_search { query: "USDC", verifiedOnly: true }
-> Set verifiedOnly: true to filter out suspicious/unverified assets
```

### NFD Lookup
```
// Look up an NFD name
api_nfd_get_nfd { nameOrID: "example.algo", view: "full", network: "mainnet" }
-> CRITICAL: Use depositAccount field for transactions, NOT other address fields!

// Get NFDs owned by an address
api_nfd_get_nfds_for_addresses {
  address: ["ALGO_ADDRESS"],
  view: "brief",
  limit: 10,
  network: "mainnet"
}
```

### Top-Up QR Code (Insufficient Funds)
```
// Generate ARC-26 QR code for easy funding
generate_algorand_uri {
  address: "[wallet_address]",
  amount: 5000000,          // Required amount including MBR and fees
  asset: 31566704,          // Optional: ASA ID for token top-ups
  note: "Fund account"
}
-> Returns URI string + SVG QR code — user scans with Pera Wallet
```

### 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. It supports multi-hop and parallel (combo) swaps for best pricing.

**Step-by-step workflow:**

| Step | Tool | Purpose |
|------|------|---------|
| 1 | `wallet_get_info` | Verify active account, check balance |
| 2 | `api_haystack_needs_optin` | Check if address needs opt-in for the target asset |
| 3 | `wallet_optin_asset` | Opt-in if needed (skip if already opted in) |
| 4 | `api_haystack_get_swap_quote` | Preview best-price quote — show user output, USD values, route, price impact |
| 5 | User confirms | Always confirm before executing — quotes are time-sensitive |
| 6 | `api_haystack_execute_swap` | All-in-one: quote + sign via wallet + submit + confirm |
| 7 | — | **Present each txId from response as explorer link** (mainnet: `https://allo.info/tx/{txId}`, testnet: `https://lora.algokit.io/testnet/transaction/{txId}`) |

**`api_haystack_get_swap_quote` parameters:**
```
{
  fromASAID: 0,             // Input asset (0 = ALGO)
  toASAID: 31566704,        // Output asset (USDC)
  amount: 1000000,          // Amount in base units
  type: "fixed-input",      // or "fixed-output"
  address: "<address>",     // Optional, for opt-in detection
  maxGroupSize: 16,         // Optional, max transaction group size
  maxDepth: 4,              // Optional, max routing depth
  network: "mainnet"
}
Returns: expectedOutput, inputAmount, usdIn, usdOut, userPriceImpact,
         route, flattenedRoute, requiredAppOptIns, protocolFees
```

**`api_haystack_execute_swap` parameters:**
```
{
  fromASAID: 0,             // Input asset
  toASAID: 31566704,        // Output asset
  amount: 1000000,          // Amount in base units
  slippage: 1,              // 1% slippage tolerance
  type: "fixed-input",      // or "fixed-output"
  note: "my swap",          // Optional text note
  maxGroupSize: 16,         // Optional
  maxDepth: 4,              // Optional
  network: "mainnet"
}
Returns: status, confirmedRound, txIds, signer, nickname, quote details,
         summary (inputAmount, outputAmount, totalFees, transactionCount)
```

**`api_haystack_needs_optin` parameters:**
```
{
  address: "<address>",
  assetId: 31566704,
  network: "mainnet"
}
Returns: { address, assetId, needsOptIn: true/false, network }
```

**Slippage guidance:**

| Pair Type | Recommended Slippage |
|-----------|---------------------|
| Stable pairs (ALGO/USDC) | 0.1-0.5% |
| Major ASA pairs | 0.5-1% |
| Volatile pairs | 1-3% |
| Low liquidity pairs | 3-5% |

Slippage is verified on the **final output** of the swap, not on individual hops.

**Swap direction examples:**
```
// "Sell 10 ALGO for USDC" — user spends exactly 10 ALGO
api_haystack_execute_swap {
  fromASAID: 0, toASAID: 31566704,
  amount: 10000000, type: "fixed-input",
  slippage: 0.5, network: "mainnet"
}

// "Buy 10 USDC with ALGO" — user receives exactly 10 USDC
api_haystack_execute_swap {
  fromASAID: 0, toASAID: 31566704,
  amount: 10000000, type: "fixed-output",
  slippage: 0.5, network: "mainnet"
}
```

**Batch swaps** — for multiple sequential swaps, repeat quote + execute for each pair:
```
For each swap pair:
  1. api_haystack_get_swap_quote { ... } -> show user
  2. User confirms -> api_haystack_execute_swap { ... }
  Each execute call gets a fresh quote — no stale quote issues
```

**Key rules for Haystack Router:**
- Always check wallet with `wallet_get_info` before any swap
- Always confirm with the user before executing (show quote details)
- The execute tool handles signing via the active wallet — no manual signing needed
- Quotes are time-sensitive — execute promptly after user confirms
- `api_haystack_execute_swap` automatically handles opt-in detection (auto opt-in enabled by default)
- Rate limit: 60 requests/min for Haystack Router API calls

**Swap error handling:**

| Error | Cause | Solution |
|-------|-------|----------|
| Slippage exceeded | Price moved beyond tolerance | Refetch quote and retry with higher slippage |
| Insufficient balance | Not enough funds | **STOP** — do NOT continue. Check with `wallet_get_info` and `wallet_get_assets`, inform user of shortfall, generate top-up QR |
| Asset not opted in | Missing opt-in | Use `wallet_optin_asset` or `api_haystack_needs_optin` to check first |
| Transaction rejected | User declined or signing failed | Retry after confirmation |
| Stale quote | Too much time between quote and execute | Refetch quote — `api_haystack_execute_swap` gets a fresh quote automatically |

### Tinyman AMM Swap

Tinyman provides direct AMM swaps through its V2 pools. Use Tinyman when you need direct pool access, liquidity management, or pool analytics. For best-price routing across multiple DEXes, prefer Haystack Router.

**Tinyman tool parameters:**
```
// Get pool info
api_tinyman_get_pool {
  asset1Id: 0,          // First asset (0 = ALGO)
  asset2Id: 31566704,   // Second asset (USDC)
  version: "v2",        // Pool version
  network: "mainnet"
}

// Get swap quote
api_tinyman_get_swap_quote {
  asset1Id: 0,          // Input asset
  asset2Id: 31566704,   // Output asset
  amount: 1000000,      // Amount in base units
  network: "mainnet"
}

// Get pool analytics (volume, TVL, fees)
api_tinyman_get_pool_analytics {
  asset1Id: 0,
  asset2Id: 31566704,
  network: "mainnet"
}
```

**Swap workflow:**

| Step | Tool | Purpose |
|------|------|---------|
| 1 | `wallet_get_info` | Verify active account, check balance |
| 2 | `api_tinyman_get_pool` | Check pool exists and has sufficient liquidity |
| 3 | `api_tinyman_get_swap_quote` | Get swap quote with transaction data |
| 4 | Build transactions from quote response | Parse the returned transaction group |
| 5 | `wallet_sign_transaction_group` | Sign the atomic transaction group |
| 6 | `send_raw_transaction` | Submit signed transactions to network |

**Liquidity management workflow:**

| Step | Tool | Purpose |
|------|------|---------|
| 1 | `api_tinyman_get_pool` | Get pool details (reserves, pool token) |
| 2 | `api_tinyman_get_pool_analytics` | Check pool APR, volume, TVL |
| 3 | `api_tinyman_get_liquidity_quote` | Get add-liquidity quote |
| 4 | Build and sign transactions from quote | Sign the group via wallet |
| 5 | `send_raw_transaction` | Submit to network |

**Pool creation workflow:**
```
1. wallet_get_info -> verify balance (pool creation requires MBR)
2. api_tinyman_get_pool_creation_quote -> get pool creation transactions
3. Build, sign, and submit the transaction group
```

**Tinyman vs Haystack Router:**
| Feature | Tinyman | Haystack Router |
|---------|---------|-----------------|
| Swap pricing | Single AMM pool | Best price across Tinyman, Pact, Folks |
| Multi-hop | No | Yes (automatic) |
| Liquidity management | Yes (add/remove) | No |
| Pool analytics | Yes | No |
| Pool creation | Yes | No |
| Signing | Manual (wallet_sign_transaction_group) | Automatic (built into execute_swap) |
| Use when | Direct pool access, liquidity, analytics | Best-price swaps, convenience |

### Query Account Information
```
- Live state: api_algod_get_account_info
- Historical data: api_indexer_lookup_account_by_id
- Transaction history: api_indexer_lookup_account_transactions
```

### NFD Resolution
```
1. api_nfd_get_nfd -> look up the .algo name
2. Extract depositAccount from response
3. Use depositAccount as transaction recipient
```

## Swap Direction Rules (Haystack Router & Tinyman)

The `type` parameter determines whether the `amount` is the exact input or the exact output. **Getting this wrong means the user spends or receives the wrong amount.**

### How to parse user intent

| User Says | Means | `type` | `amount` is | `fromASAID` | `toASAID` |
|-----------|-------|--------|-------------|-------------|-----------|
| "Buy 10 ALGO with USDC" | Want exactly 10 ALGO out | `fixed-output` | 10000000 (the ALGO) | USDC | ALGO |
| "Buy 10 USDC with ALGO" | Want exactly 10 USDC out | `fixed-output` | 10000000 (the USDC) | ALGO | USDC |
| "Sell 10 ALGO for USDC" | Spend exactly 10 ALGO | `fixed-input` | 10000000 (the ALGO) | ALGO | USDC |
| "Swap 10 ALGO to USDC" | Spend exactly 10 ALGO | `fixed-input` | 10000000 (the ALGO) | ALGO | USDC |
| "Use 10 ALGO to buy USDC" | Spend exactly 10 ALGO | `fixed-input` | 10000000 (the ALGO) | ALGO | USDC |
| "Buy USDC for 10 ALGO" | Spend exactly 10 ALGO | `fixed-input` | 10000000 (the ALGO) | ALGO | USDC |
| "Get me 5 USDC" | Want exactly 5 USDC out | `fixed-output` | 5000000 (the USDC) | (ask user) | USDC |

### Rules
1. **"Buy X of Y"** -> user wants exactly X of Y as output -> `type: "fixed-output"`, `amount` = X in base units, `toASAID` = Y
2. **"Sell/swap/convert X of Y"** -> user wants to spend exactly X of Y as input -> `type: "fixed-input"`, `amount` = X in base units, `fromASAID` = Y
3. **"Buy Y for/with X of Z"** -> user specifies exact input spend -> `type: "fixed-input"`, `amount` = X in base units, `fromASAID` = Z
4. **If ambiguous, ASK the user** — never guess. Wrong direction = wrong amount spent/received.

### fixed-input vs fixed-output behavior
- **`fixed-input`**: The `amount` field is the **exact input** the user will spend. The output varies based on market price. User knows exactly what they pay.
- **`fixed-output`**: The `amount` field is the **exact output** the user will receive. The input varies based on market price. User knows exactly what they get.

### Amounts
- Amounts are always in **base units** (microAlgos for ALGO, smallest unit for ASAs)
- ASA IDs: 0 = ALGO, 31566704 = USDC, 312769 = USDT, etc.
- Always check the asset's `decimals` field with `api_algod_get_asset_by_id` before computing amounts

## Common Mainnet Assets

| Asset | ASA ID | Decimals | Description |
|-------|--------|----------|-------------|
| ALGO | native (0) | 6 | Native Algorand token |
| USDC | 31566704 | 6 | USD Coin stablecoin |
| USDT | 312769 | 6 | Tether USD stablecoin |
| goETH | 386192725 | 8 | Wrapped Ethereum |
| goBTC | 386195940 | 8 | Wrapped Bitcoin |

**Always verify asset IDs before transactions — scam tokens may use similar names.** Use `pera_asset_verification_status` to check verification tier (verified, trusted, suspicious, unverified).

## Amounts and Decimals

All amounts in tool parameters are in **base units** (smallest denomination):

| Asset | Decimals | 1 Whole Token = | Example |
|-------|----------|-----------------|---------|
| ALGO (ASA 0) | 6 | 1,000,000 microAlgos | 1 ALGO = `1000000` |
| USDC (ASA 31566704) | 6 | 1,000,000 micro-units | 5 USDC = `5000000` |
| USDT (ASA 312769) | 6 | 1,000,000 micro-units | 1 USDT = `1000000` |
| Custom ASAs | varies | Depends on `decimals` field | Check with `api_algod_get_asset_by_id` |

Always check an asset's `decimals` field with `api_algod_get_asset_by_id` before computing amounts for unfamiliar assets.

## Transaction Simulation

Before submitting critical or high-value transactions, use simulation to verify they will succeed:
```
simulate_transactions {
  txnGroups: [ ...transaction group... ],
  allowEmptySignatures: true,
  allowMoreLogging: true,
  network: "mainnet"
}
```
This catches errors (insufficient balance, wrong parameters, logic failures) without spending real funds.

## Alpha Arcade — Agent Guide

### Units

All prices and quantities in tool **inputs** use **microunits**: 1,000,000 = $1.00 or 1 share.

| Human value | Microunit value |
|---|---|
| $0.50 | 500,000 |
| $0.05 slippage | 50,000 |
| 1 share | 1,000,000 |
| 30 shares | 30,000,000 |

Tool **outputs** from read tools (get_orderbook, get_open_orders, get_positions) return pre-formatted strings like "$0.50" and "2.50 shares". Write tools accept raw microunit integers.

### Market Data Model

#### Binary markets
A standard yes/no market has a single `marketAppId`, `yesAssetId`, and `noAssetId`. Use `marketAppId` for all trading calls.

#### Multi-choice markets
Multi-choice markets (e.g., "Who wins the election?") appear with an `options[]` array. Each option is its own binary market with its own `marketAppId`.

**Always trade using the option's `marketAppId`, not the parent.**

### Orderbook Mechanics

#### Four-sided book
The orderbook has four sides: YES bids, YES asks, NO bids, NO asks.

#### Cross-side equivalence
Because YES + NO always = $1.00:
- A **YES bid at $0.30** is equivalent to a **NO ask at $0.70**
- A **NO bid at $0.71** is equivalent to a **YES ask at $0.29**

#### Limit vs market orders
- **Limit order** (`alpha_create_limit_order`): Sits on the orderbook at your exact price.
- **Market order** (`alpha_create_market_order`): Auto-matches against existing orders within your slippage tolerance.

### Collateral

Every order locks ~0.957 ALGO as MBR for the on-chain escrow app. This is refunded on cancel/fill.
Buy orders also lock USDC collateral = quantity x (price + slippage) + fees.
Sell orders lock outcome tokens as collateral.

### Key Workflows

#### Buying shares
1. `alpha_get_live_markets` — find a market
2. `alpha_get_orderbook` — check available liquidity
3. `alpha_create_market_order` (auto-matches) or `alpha_create_limit_order` (rests on book)
4. Save the returned `escrowAppId` — you need it to cancel
5. Present returned txIds as clickable explorer links (mainnet: `https://allo.info/tx/{txId}`, testnet: `https://lora.algokit.io/testnet/transaction/{txId}`)

#### Checking your portfolio
1. `alpha_get_positions` — see all YES/NO token balances
2. `alpha_get_open_orders` with `marketAppId` for open orders on a specific market

#### Cancelling an order
1. `alpha_get_open_orders` — find the `escrowAppId` and `owner`
2. `alpha_cancel_order` with `marketAppId`, `escrowAppId`, and `orderOwner`

#### Claiming from a resolved market
1. `alpha_get_positions` — find the winning token's `assetId`
2. `alpha_claim` with `marketAppId` and `assetId`

### Common Pitfalls

- **Multi-choice markets**: Use `options[].marketAppId`, not the parent.
- **Prices are microunits**: $0.50 = 500,000, not 0.5.
- **Orderbook cross-side**: Check YES asks AND NO bids (complement) for best price.
- **Save escrowAppId**: It's the only way to cancel or reference your order later.
- **Trading requires wallet**: Read-only tools work for everyone, but trading uses your MCP wallet.

## External Links

- GoPlausible: https://goplausible.com
- Algorand: https://algorand.co
- Algorand Developer Docs: https://dev.algorand.co/
- Algorand x402: https://x402.goplausible.xyz
- Algorand x402 Test Endpoints: https://example.x402.goplausible.xyz/
- Testnet Faucet: https://lora.algokit.io/testnet/fund
- Testnet USDC Faucet: https://faucet.circle.com/
- Allo.info (Block Explorer): https://allo.info
- Pera Explorer: https://explorer.perawallet.app/