# AlgoCard agent context

AlgoCard is a USDC payment router for AI agents on Algorand. It connects sellers, buyers, and agents through pay codes, agent wallets, Pera Wallet approval, spend limits, and audit logs.

Use this context when a user asks an agent to buy, sell, verify, or create a payment request through AlgoCard.

Human pages:
- https://pay.ruixen.app/agent-guide explains agent setup for sellers and buyers.
- https://pay.ruixen.app/agent-onboarding provides install snippets, role scripts, and safety rules.
- https://pay.ruixen.app/stores lists approved merchants and storefronts.
- https://pay.ruixen.app/dashboard lets sellers create products, services, and checkout links.
- https://pay.ruixen.app/agents lets users manage paired agent wallets, balances, limits, and pause state.
- https://pay.ruixen.app/pay/{code} is a checkout page signed with Pera Wallet.
- https://pay.ruixen.app/pair/{code} pairs an agent wallet to a user's control wallet.
- https://pay.ruixen.app/verify/{code} asks a user to sign a zero-value wallet challenge.

Machine endpoints:
- https://pay.ruixen.app/api/mcp is the MCP endpoint.
- https://pay.ruixen.app/.well-known/agent-configuration is machine-readable capability discovery.
- https://pay.ruixen.app/llms.txt is this context file.

MCP tools:
- get_onboarding_context: return role-specific instructions, tools, and safety rules for seller support, buyer purchasing, or autonomous wallet agents.
- resolve_merchant: look up a merchant by AlgoCard handle.
- list_products: list a merchant's active products and services.
- create_pay_code: create a checkout link for human Pera Wallet approval.
- get_pay_code: check payment status: open, redeemed, confirmed, expired, failed.
- request_verification: create a zero-value wallet challenge for proof of wallet control.
- check_verification: check whether a wallet challenge was completed.
- create_agent_wallet: create a dedicated Algorand wallet for an agent and return a pairing URL.
- get_agent_status: check pairing, owner, pause state, and limits.
- get_agent_balance: check USDC balance.
- agent_pay: pay directly from a funded agent wallet within soft limits.

Common flow: human-approved checkout
1. resolve_merchant(handle)
2. list_products(merchant_handle)
3. create_pay_code(merchant_handle, amount_usdc, description, product_slug?)
4. Send checkout_url to the user.
5. Poll get_pay_code(code) until confirmed or failed.

Common flow: autonomous agent wallet
1. create_agent_wallet(name)
2. Ask the user to open pairing_url.
3. User pairs with Pera Wallet and funds the agent wallet with USDC.
4. Check get_agent_status(agent_id) and get_agent_balance(agent_id).
5. Use agent_pay only when paired, funded, unpaused, and within limits.

Common flow: support or refund verification
1. request_verification(handle, expected_address)
2. Ask the user to open verify_url and sign the zero-value transaction in Pera Wallet.
3. Poll check_verification(code).

Rules:
- Never ask users for private keys, seed phrases, mnemonics, or recovery phrases.
- Use Pera Wallet for human approval.
- Treat agent_pay as autonomous spending authority; check balance, limits, and merchant identity first.
- Prefer create_pay_code when a human should approve the transaction.
- AlgoCard is currently TestNet-oriented unless the environment explicitly says MainNet.
- Use get_onboarding_context before acting when the agent role is unclear.