Install and operate the AgentPay SDK. Trigger this when an agent needs to install `agentpay`, explain AgentPay SDK capabilities without probing the machine first, bind Link for Fiat card payments, set up or reuse a Crypto wallet, check funding, generate funding instructions or a QR, guide the user through policy changes in the TUI or exact admin CLI when explicitly requested, route manual approvals to the local admin approval commands, execute transfers, approvals, or broadcasts using the current CLI behavior instead of stale examples, or use supported plugin-backed merchant payment flows when explicitly relevant.
Instrucciones de origen · Vista previa de solo lectura
name
agentpay-sdk
description
Install and operate the AgentPay SDK. Trigger this when an agent needs to install `agentpay`, explain AgentPay SDK capabilities without probing the machine first, bind Link for Fiat card payments, set up or reuse a Crypto wallet, check funding, generate funding instructions or a QR, guide the user through policy changes in the TUI or exact admin CLI when explicitly requested, route manual approvals to the local admin approval commands, execute transfers, approvals, or broadcasts using the current CLI behavior instead of stale examples, or use supported plugin-backed merchant payment flows when explicitly relevant.
Installer payment choice: use AGENTPAY_SETUP_PAYMENT_METHOD=fiat for Link onboarding, AGENTPAY_SETUP_PAYMENT_METHOD=crypto for local wallet setup, or AGENTPAY_SETUP_PAYMENT_METHOD=none to install only.
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.
Fiat setup and card credentials use the bundled Stripe Link CLI through agentpay link. Users bind their Link account with agentpay link onboard, approve every spend request in the Link app, and receive one-time card credentials written to a local 0600 file.
@worldlibertyfinancial/agentpay-sdk/link exposes helper functions for third-party agents that integrate through the AgentPay Link facade.
agentpay wallet --json is the wallet reuse check.
agentpay admin setup is the first-run wallet setup path on macOS and Linux.
agentpay link status --json is the Link account reuse check.
agentpay link payment-methods --json lists Link payment methods.
agentpay link card ... --output-file <PATH> creates a Link spend request, requests approval, polls, and writes full card credentials locally while stdout stays redacted.
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.
Wallet Model
AgentPay supports two payment setup paths.
Fiat with Link: agentpay link onboard, then agentpay link card ... for one-time cards or agentpay link mpp ... for Link-backed MPP/SPT flows.
Crypto with local wallet: agentpay admin setup on macOS or Linux.
The local Rust daemon manages crypto keys, policy enforcement, manual approval, and wallet backup.
Crypto supports transfer, transfer-native, approve, broadcast, x402, and mpp.
Tempo session mode is available through crypto 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 Link access tokens, refresh tokens, card numbers, CVCs, or full card credential files 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.
If a flow needs Link authentication, move the user to agentpay link onboard or a third-party integration that calls onboardLinkAccount; the user approves the connection in Link.
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
Classify the request as explain capabilities, install, choose payment method, setup Fiat Link, create Link card, setup crypto 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.
If the user is only asking what this skill can do, answer from What This Skill Covers and stop there.
If the user wants Fiat or card-based agent payments, start with agentpay link status --json.
If Link is not authenticated, use agentpay link onboard.
List payment methods with agentpay link payment-methods --json and use the selected id as --payment-method-id.
For a card purchase, use agentpay link card --payment-method-id <id> --merchant-name <name> --merchant-url <url> --amount <cents> --context <100+ char explanation> --output-file <PATH>. Do not print full card details into chat.
If the user wants third-party program integration, use the @worldlibertyfinancial/agentpay-sdk/link helpers so the integration stays on the AgentPay Link facade.
For crypto wallet or onchain payment work, start with agentpay config show --json.
Run agentpay wallet --json to check wallet status.
If the wallet is unavailable and the task needs crypto, tell the user to run agentpay admin setup locally.
If the wallet exists but the user needs to re-run setup without changing vaults, use agentpay admin setup --reuse-existing-wallet.
If the user needs disaster recovery on a new machine and has an encrypted backup, use agentpay admin setup --restore-wallet-from <PATH>.
For policy configuration, default to agentpay admin tui.
If a request is queued for manual approval, tell the user it is waiting for approval and use the local admin CLI approval commands.
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.
For plugin-backed merchant payments, prefer Link cards for Fiat card payments; use Bitrefill only when the user specifically wants Bitrefill or a gift/prepaid-card route.
If the user did not specify network or asset for a crypto payment, fill in bsc and before asking follow-up questions.
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
Link account check: agentpay link status --json
Link onboarding: agentpay link onboard
Link payment methods: agentpay link payment-methods --json
Link card: agentpay link card --payment-method-id <id> --merchant-name <name> --merchant-url <url> --amount <cents> --context <100+ char explanation> --output-file <PATH>
Link advanced passthrough: agentpay link spend-request ..., agentpay link mpp ..., agentpay link serve ...
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>
Manual approval decision: agentpay admin approve-manual-approval-request or agentpay admin reject-manual-approval-request
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 exact CLI commands, use:
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.
