AgentPay SDK#

Use this skill as an operator playbook. Do not make the user design command flows or policy objects from scratch.

What This Skill Covers#

If the user asks what this skill can do, answer from this list first. Do not probe the local machine unless the user is asking you to act.

• install agentpay
• bootstrap agentpay and the AgentPay skill pack with the one-click installer
• explain whether the wallet can be reused or needs first-run setup
• guide the user through local wallet setup (self-custodial daemon mode)
• export, verify, and restore encrypted offline wallet backups
• check balances and stop for funding when money or gas is missing
• generate funding instructions and a QR
• send native assets, send ERC-20 tokens, approve allowances, and broadcast transactions
• pay x402-protected APIs (EIP-3009 signing)
• pay MPP-protected APIs on any EVM chain (charge on any chain, session on Tempo)
• use supported plugin-backed merchant payment flows when relevant
• guide the user through policy configuration in the TUI
• route manual approvals to the local admin approval commands
• surface pending manual approvals and tell the user how to approve or reject them

Ground Truth#

• Use agentpay --help and the relevant subcommand help as the source of truth when examples disagree.
• One-click bootstrap: curl -fsSL https://wlfi.sh | bash
• One-click skills only: curl -fsSL https://wlfi.sh | bash -s -- --skills-only
• One-click update: rerun curl -fsSL https://wlfi.sh | bash
• One-click packaged runtime bundles are available on macOS and Linux. Managed wallet setup is supported on both platforms after install.
• Source install or update: from the repo checkout run pnpm install && npm run build && npm run install:cli-launcher && npm run install:rust-binaries
• Managed wallet bootstrap commands such as agentpay admin setup, agentpay admin tui, agentpay admin reset, and agentpay admin uninstall are supported on macOS and Linux. The managed daemon uses launchd on macOS and system systemd on Linux. Agent auth storage uses macOS Keychain on macOS and Linux Secret Service on Linux.
• agentpay wallet --json is the wallet reuse check.
• agentpay admin setup is the first-run wallet setup path on macOS and Linux.
• Plugin-specific help lives under the current CLI. For Bitrefill, use agentpay bitrefill --help.
• Browser-based relay and web approval are unsupported in this release.
• agentpay admin set-relay-config and agentpay admin get-relay-config are legacy compatibility commands and return unsupported.
• agentpay admin setup --reuse-existing-wallet is the managed-daemon recovery / local re-setup path when the current vault should be preserved.
• agentpay admin setup --restore-wallet-from <PATH> restores the same wallet from an encrypted offline backup on macOS or Linux.
• agentpay admin wallet-backup export --output <PATH> creates an encrypted offline backup.
• Do not use sudo agentpay ....
• Do not tell users to run agentpay daemon directly.

Wallet Model#

AgentPay uses a self-custodial local daemon wallet.

• Setup on macOS or Linux: agentpay admin setup
• Local Rust daemon manages keys, policy enforcement, manual approval, and wallet backup
• Supports transfer, transfer-native, approve, broadcast, x402, and mpp
• Tempo session mode is available through agentpay mpp

Default Payment Assumption#

• Default network: bsc
• Default asset for unspecified payments: USD1
• Default USD1 contract on BSC: 0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d
• Default gas asset on BSC: BNB

Secure Input Rule#

• Never ask the user to paste VAULT_PASSWORD into chat.
• Never ask the user to paste a wallet backup password into chat.
• Never ask the user to paste plugin session material into chat, including Bitrefill cookies, captcha tokens, or browser session material.
• Never collect or store the vault password inside the agent.
• If a flow needs vault input, move the user to a secure local prompt.
• For first-run setup, tell the user to run agentpay admin setup locally and follow the secure prompt there.
• After first-run setup, strongly prefer agentpay admin wallet-backup export --output <PATH> unless the user already has a verified backup.
• For daemon recovery with an existing wallet, tell the user to run agentpay admin setup --reuse-existing-wallet locally.
• For machine loss or local wallet loss when the user has a backup, tell them to run agentpay admin setup --restore-wallet-from <PATH> locally.
• For policy changes, default to agentpay admin tui on macOS or Linux.
• For manual approvals, prefer the local admin CLI approval commands.
• agentpay transfer --broadcast, agentpay transfer-native --broadcast, agentpay approve --broadcast, and agentpay bitrefill buy --broadcast keep the original CLI process alive while waiting for manual approval. Do not tell the user to rerun those commands after approving.
• If the original broadcast command has already exited but the request is approved, use agentpay admin resume-manual-approval-request --approval-request-id <UUID> instead of reconstructing the transaction by hand.

Deterministic Flow#

1. Classify the request as explain capabilities, install, setup wallet, back up wallet, restore wallet, fund wallet, set policy, send native asset, send ERC-20, approve allowance, broadcast raw tx, pay MPP API, plugin-backed merchant payment, or uninstall.
2. If the user is only asking what this skill can do, answer from What This Skill Covers and stop there.
3. For wallet or payment work, start with agentpay config show --json.
4. Run agentpay wallet --json to check wallet status.
5. If the wallet is unavailable and the task needs one, tell the user to run agentpay admin setup locally.
6. If the wallet exists but the user needs to re-run setup without changing vaults, use agentpay admin setup --reuse-existing-wallet.
7. If the user needs disaster recovery on a new machine and has an encrypted backup, use agentpay admin setup --restore-wallet-from <PATH>.
8. For policy configuration, default to agentpay admin tui.
9. If a request is queued for manual approval, tell the user it is waiting for approval and use the local admin CLI approval commands.
10. For transfer --broadcast, transfer-native --broadcast, approve --broadcast, and bitrefill buy --broadcast, tell the user to keep that original command running while they approve it.
11. For plugin-backed merchant payments, use the relevant current CLI plugin flow. If the user is specifically using Bitrefill, or the request is to pay a traditional merchant that only accepts cards and Bitrefill is the supported path, use Bitrefill.
12. If the user did not specify network or asset for a payment, fill in bsc and USD1 before asking follow-up questions.
13. Before any outbound action, check funding.
14. If funding is missing, stop and ask the user to top up the wallet.
15. Only then run the exact current CLI command.

Funding Rule#

• Treat a fresh wallet as unfunded until the balance check proves otherwise.
• For native transfers, check native balance.
• For ERC-20 transfers and approvals, check both token balance and native gas balance.
• For Bitrefill purchases, check the settlement asset and the native gas asset on the chosen EVM chain before buying with --broadcast.
• For the default path, tell the user they may need both USD1 for value and BNB for gas.
• When funding is missing, give the user:
  • wallet address
  • network and chain id
  • asset needed for value, if relevant
  • asset needed for gas
  • funding URI
  • a rendered QR image if the host supports markdown images
  • a qrUrl as fallback

Bitrefill Plugin Rule#

• For payment to traditional merchants that only accept cards, use bitrefill.
• If the merchant is present on bitrefill, directly purchase the gift card.
• Otherwise, purchase a prepaid VISA card.
• Bitrefill in this repo is EVM-only. Do not propose bitcoin, lightning, solana, or other non-EVM settlement methods.
• Default to preview first with agentpay bitrefill buy ... and add --broadcast only when the user wants to pay immediately.
• In Bitrefill quote and preview output, treat amount as the raw onchain base-unit integer, not a human-decimal amount. Examples: ETH base units are wei, and amount: 1000000 with decimals: 6 means 1 USDC.
• agentpay bitrefill buy --broadcast pays through the existing Rust daemon signing path. It is not a separate wallet flow.
• If Bitrefill triggers a browser challenge, let the CLI bootstrap a local browser session and have the user complete the challenge locally.
• Bitrefill checkout still follows the normal funding and manual-approval rules in this skill.

Current Command Shapes#

• Wallet check: agentpay wallet --json
• Setup on macOS or Linux: agentpay admin setup
• Reuse existing wallet during setup recovery: agentpay admin setup --reuse-existing-wallet
• Restore wallet from encrypted backup: agentpay admin setup --restore-wallet-from <PATH>
• Export encrypted wallet backup: agentpay admin wallet-backup export --output <PATH>
• Verify encrypted wallet backup: agentpay admin wallet-backup verify <PATH>
• Native transfer: agentpay transfer-native --network <name> --to <address> --amount <amount>
• ERC-20 transfer: agentpay transfer --network <name> --token <address> --to <address> --amount <amount>
• Approve: agentpay approve --network <name> --token <address> --spender <address> --amount <amount>
• Policy-checked raw request: agentpay broadcast --network <name> --to <address> --value-wei <wei> ...
• Sign and send: agentpay tx broadcast --network <name> --rpc-url <url> --from <address> --to <address> --value-wei <wei> ...
• Policy editing on macOS or Linux: agentpay admin tui
• Default token limits and live sync for an existing wallet: agentpay admin token set-chain <tokenKey> <chainKey> --per-tx <amount> --daily <amount> --weekly <amount> [--vault-password-stdin] [--non-interactive]
• Manual approval policy: agentpay admin add-manual-approval-policy --network <id> --min-amount-wei <wei> --max-amount-wei <wei> ...
• Manual approval queue: agentpay admin list-manual-approval-requests
• Manual approval decision: agentpay admin approve-manual-approval-request or agentpay admin reject-manual-approval-request
• Resume approved broadcast-backed manual approval: agentpay admin resume-manual-approval-request --approval-request-id <UUID>
• Bitrefill search: agentpay bitrefill search --query <text>
• Bitrefill product: agentpay bitrefill product --slug <slug>
• Bitrefill buy quote: agentpay bitrefill buy --slug <slug> --amount <value> [--payment-method <method>]
• Bitrefill quote fields: availablePaymentMethods[].amount is the raw onchain base-unit integer.
• Bitrefill buy and pay: agentpay bitrefill buy --slug <slug> --amount <value> --payment-method <method> --email <email> --broadcast [--no-wait]
• Bitrefill preview payment fields: payment.amount is the raw onchain base-unit integer.
• Bitrefill invoice list: agentpay bitrefill invoice list
• Bitrefill invoice lookup: agentpay bitrefill invoice get --invoice-id <id> [--access-token <token>]
• Bitrefill invoice wait: agentpay bitrefill invoice wait --invoice-id <id> [--access-token <token>] [--timeout <sec>]

Policy Rules#

• Do not ask open-ended policy questions.
• Map user requests into one of these:
  • keep the existing policy
  • tighten default token limits in the TUI
  • add a manual approval range in the TUI
  • inspect or resolve manual approval requests
• Policy work should default to agentpay admin tui.
• If the user explicitly wants exact CLI commands for default per-token limits, use agentpay admin token set-chain ...; it updates saved config and attempts to refresh the live daemon attachment for the existing wallet.
• agentpay admin token set-chain ... needs a local vault-password prompt or --vault-password-stdin. If the live apply step fails, do not claim the saved config or daemon policy changed.
• Destination-specific overrides are a TUI path. Do not claim they were applied unless the user actually went through the TUI.
• Do not ask for VAULT_PASSWORD in chat for policy work. If the CLI or UI prompts locally, that secure prompt happens outside chat.

Manual Approval Rule#

• Treat a manual approval hit as pending, not failed.
• Tell the user the request is waiting for their approval.
• Use the local admin CLI approval commands first.
• For transfer --broadcast, transfer-native --broadcast, approve --broadcast, and bitrefill buy --broadcast, tell the user not to rerun the original command after approval. The CLI polls every 2 seconds for up to 5 minutes and continues automatically if the same approval request is approved.
• If the original broadcast command is already gone after approval, use agentpay admin resume-manual-approval-request --approval-request-id <UUID>.
• agentpay broadcast and other non-auto-waiting flows still print approval details and exit.
• If the user explicitly asks for raw CLI commands, use:
  • agentpay admin list-manual-approval-requests
  • agentpay admin approve-manual-approval-request --approval-request-id <UUID>
  • agentpay admin resume-manual-approval-request --approval-request-id <UUID>
  • agentpay admin reject-manual-approval-request --approval-request-id <UUID> --rejection-reason <TEXT>

Minimal Clarification Rule#

• If the user says "send money" and omits network or asset, do not ask for them first. Use the defaults.
• Only ask for the remaining critical fields:
  • amount
  • recipient
  • spender

MPP Services#

AgentPay can pay for any MPP-enabled API using agentpay mpp. No API keys or accounts are needed — payment happens inline via the HTTP 402 protocol. The CLI resolves the payment chain from the server challenge and supports any EVM-compatible network.

• Discover current MPP LLM/search services from https://mpp.dev/services/llms.txt. Do not rely on a static in-repo service directory.
• --amount is optional. When omitted, the CLI pays the server's challenge amount automatically. When provided, the CLI verifies the challenge amount matches before paying.
• The wallet must hold the payment token on the chain specified by the service challenge.
• mpp supports charge on any EVM-compatible chain.
• Session mode (escrow channels) is Tempo-only.

Extra References#

• Read references/capabilities.md only when you need exact flags or examples.
• Read references/demo-walkthrough.md only when you need a short live demo script.