# Confirmation and authorization rules
Source: https://docs.useagentbank.com/ai-guides/confirmation-rules
Distinguish standing authorization, user confirmation, World ID, wallet execution, and fiat funding.
| Boundary | Meaning |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Platform threshold | One input to AgentBank's payment-approval policy |
| Payment summary confirmation | User explicitly approves the recipient, amounts, fees, route, and expiry before creation or plan submission |
| World ID authorization | A separate payment-specific approval when Core returns `approval_required` |
| Wallet execution confirmation | Authorization to execute a current on-chain instruction when the active policy requires it |
| Spending-grant funding choice | A new, explicit hosted-user choice for the current crypto-deposit instruction |
| Browser fiat funding | A payer manually completes the current production bank or QR instruction |
The deployed tool reference is authoritative for exact fields:
* `create_payment`: `confirmed_by_user=true`
* `submit_payment_plan`: `confirmed_by_user=true` after one consolidated review
* `execute_payment_instruction`: `confirmed_by_user=true`
* `request_spending_grant`: confirmation of scope and limits
* `fund_payment_with_grant`: a new confirmation for the current instruction
* `approve_token`: confirmation when a transaction is required
* `correct_payment_recipient`: explicit confirmation
* `update_recipient`: explicit confirmation
* `revoke_agent`: `confirm=true`
* `cancel_payment`: caller obtains confirmation before calling
An agent must set a confirmation field only when the corresponding current user
confirmation permits it. Confirmation to create, approve, or continue a
payment does not authorize hosted wallet funding.
# Example prompts
Source: https://docs.useagentbank.com/ai-guides/conversation-patterns
Tell your assistant what you want to do in everyday language.
Start with your goal. Your assistant should ask for missing details, check
available options, and show you the complete payment for confirmation before
proceeding. You do not need to know the names of tools or how payments are routed.
## Check your connection
> “Is my AgentBank account connected and ready to use?”
## Try a payment without real money
> “Help me try a payment in AgentBank staging using mock tokens.”
See [Environment](/getting-started/environment).
## Add money to your wallet
> “I want to pay in PHP and receive USDC in my AgentBank wallet. What are my options?”
## Collect from someone else
> “Help me collect 2,000 PHP from a customer into my AgentBank wallet. Can I share a payment link?”
If a link is not available, your assistant can provide the bank or QR
instructions for that payment. It can track whether the collection was paid,
but cannot identify who paid it.
## Pay a bank recipient
> “Send my saved recipient enough USDC for them to receive 1,000,000 VND.”
## Compare conversion costs
> “How much PHP would I need to pay for my recipient to receive 10,000,000 VND, including fees?”
## Track or recover a payment
> “Has my payment to Linh completed?”
> “I already sent the money, but the payment still looks pending. What should I do?”
## Create a payment plan
> “I need to pay these three recipients. Help me review them together as a payment plan.”
## Reopen a payment card
> “I closed the payment card. Show me the current instructions again.”
## Explore wallet funding options
> “Can I use a spending grant for this payment? Explain the limits before I decide.”
Spending grants are available for eligible hosted crypto deposits, not fiat
payments or swaps. Asking about a grant does not authorize its use.
## Pay for an x402-protected resource
> “This service asks for an x402 payment. Can you show me what it costs to access it?”
This is a specialized developer workflow; see [x402 payments](/payments/x402-payments).
# Instructions for your agent
Source: https://docs.useagentbank.com/ai-guides/instructions-for-your-agent
A concise operating contract for agents using AgentBank MCP.
Use the canonical [AgentBank Pay skill](https://useagentbank.com/SKILL.md)
for the complete workflow. The following is a readable summary.
```text theme={null}
Before AgentBank work, inspect the available MCP surface and call whoami first.
If local onboarding tools are present and credentials are missing, begin
onboarding once, show the browser authorization URL, and wait with the same
enrollment ID. If hosted spending-grant tools are present, use OAuth identity
and never run local onboarding.
Use AgentBank MCP tools rather than direct HTTP requests or hand-built payment
payloads. Use canonical asset objects and decimal-string amounts. Never infer a
recipient, wallet, bank account, token contract, chain, decimals, or calldata.
Estimate without a recipient. Before durable creation, collect a recipient
that satisfies the returned recipient requirements and show the complete
recipient, source and destination amounts, every fee and fee currency, route,
and expiry. Follow the returned approval status; do not infer a fixed threshold.
Use stable request IDs for identical logical retries. Execute only the current
Core-owned instruction. A transaction receipt is not final payment completion;
trust get_payment. On hosted OAuth, keep approval, funding, and progress cards
separate, and require a new user choice before spending-grant funding. Never
expose partner identity, secrets, Privy tokens, wallet keys, or World ID proofs.
```
This summary does not replace the canonical skill or the live MCP instructions.
# Payment decision guide
Source: https://docs.useagentbank.com/ai-guides/payment-decision-guide
Choose the correct AgentBank journey from the user's source, destination, and recipient.
```mermaid theme={null}
flowchart TD
S{"Source asset"}
S -->|"Fiat"| D{"Destination"}
S -->|"Crypto"| C{"Destination"}
D -->|"Crypto"| ON["Direct on-ramp"]
D -->|"Fiat"| FF["Explicit fiat-to-fiat route"]
C -->|"Same-chain crypto"| SW["Same-chain swap"]
C -->|"Fiat with direct pair"| OFF["Direct off-ramp"]
C -->|"Fiat without direct pair"| TF["Explicit token-to-fiat route"]
```
Before routing, collect:
* source asset and chain, or source fiat;
* exact-source or exact-destination mode;
* amount;
* destination asset or fiat currency;
* destination country;
* optional routing preference.
Estimate the route before asking for a recipient. For a fiat destination, use
the returned `recipient_requirements` to ask the user which instrument to use
and collect only that instrument's required fields before creation.
If no live route exists, explain that it is currently unavailable. Do not
invent a corridor, split the payment, or silently change chains.
# Recipient rules
Source: https://docs.useagentbank.com/ai-guides/recipient-rules
Prevent guessed, ambiguous, or unvalidated payment destinations.
1. Never infer a wallet address or bank account from weak context.
2. Search saved recipients when the user names someone known.
3. Ask the user to choose if multiple records match.
4. Estimate without a recipient, then choose exactly one payment instrument
from the returned `recipient_requirements`.
5. Call `get_supported_bank_names` before a hosted bank-transfer recipient when
the lookup is available. Otherwise submit the user's bank name for Core to
validate; do not force QR.
6. Call `create_recipient` before `create_payment` when input arrives as bank
fields, pasted text, QR content, or a QR image.
7. Use only the canonical fields returned by AgentBank.
8. Ask only for missing or invalid fields listed by the tool.
9. Do not treat `verified=false` as automatic route invalidity.
10. Explain that `update_recipient` creates a replacement record.
The fixed fiat instrument contracts are:
| Instrument | Required fields |
| --------------- | ------------------------------------------------------------------ |
| `qr` | `country`, `qr_content` |
| `bank_transfer` | `country`, `bank_name`, `account_number`, `holder_name` |
| `mobile_money` | `country`, `mobile_money_network_code`, `mobile_money_destination` |
A text-only screenshot is not OCR input. Ask the user to provide its visible
details as pasted text or structured bank information.
# Routing strategy
Source: https://docs.useagentbank.com/ai-guides/routing-strategy
Select direct or two-step routes using live pairs and complete executable outcomes.
* Use `list_quote_book_pairs` for live direct corridors.
* Use `browse_quote_book` for anonymous rough bands.
* Use `estimate_payment` for the complete executable outcome.
* Compare destination output, all fees and fee currencies, expiry, eligibility,
route steps, and user preference.
* Use an explicit settlement asset for two-step routes.
* Preserve the requested amount exactness, chain, and recipient.
Reuse an unexpired `estimate_ready` result when the economic inputs are
unchanged. Re-estimate only after expiry, a material input change,
`QUOTE_EXPIRED`, or `PRICE_MISMATCH`, then reconfirm refreshed terms.
Partner identity is intentionally hidden. Route selection must use economic and
execution properties rather than partner names.
There is no automatic Core route planner for two-step journeys. The agent must
select a common active settlement asset from live pairs.
# Safety and recovery
Source: https://docs.useagentbank.com/ai-guides/safety-and-recovery
Apply the non-negotiable safeguards for AgentBank payment workflows.
## Secret handling
Never request or reveal private keys, seed phrases, AgentBank JWTs, Privy
tokens, authorization keys, or World ID proofs.
## Recipient and amount integrity
Use canonical recipient and asset data. Show the complete recipient, amounts,
fees, route, and expiry at the authorization boundary.
## Instruction integrity
Execute only the current Core-owned payment instruction. Never construct
calldata or substitute the wallet, chain, token, amount, target, or spender.
On hosted OAuth, do not inspect or use spending grants in the same turn that
the funding card is shown. Wait for a new explicit user choice for the current
crypto-deposit instruction. Spending grants never fund fiat instructions or
swaps.
## Idempotent recovery
Reuse a request ID only for the same logical request and payload. Preserve the
same execution request ID after an ambiguous submission.
## Durable completion
A transaction receipt is not final payment completion. Trust `get_payment`.
Never fund the downstream step of a linked two-step payment separately.
## Escalation
If funds moved and automated recovery is unavailable, contact
[AgentBank support](/support/contact) with safe diagnostic identifiers.
# Agent verification and gas
Source: https://docs.useagentbank.com/autonomy/agentkit-and-gas
Verify your linked wallet and learn when transaction gas may be sponsored.
AgentKit verification can make your linked AgentBank wallet eligible for
sponsored transaction gas where supported.
```text theme={null}
Check whether my AgentBank wallet needs AgentKit verification and help me complete it.
```
Open the verification link your agent provides and complete the requested
action in World App. Return to the conversation so the agent can check the result.
Verification does not guarantee free gas for every transaction. It is separate
from identity verification, your approval threshold, and payment-specific
World ID approval.
# Set your approval threshold
Source: https://docs.useagentbank.com/autonomy/configure-thresholds
Choose when your connected agent should require additional World ID approval.
Open [app.useagentbank.com](https://app.useagentbank.com) to view or change your
connected agent's payment-approval threshold.
The threshold helps determine which payments can proceed without an additional
World ID action. AgentBank may still require approval based on the current
payment and account policy. Follow the approval request shown for that payment.
## Change it through a local agent
Local MCP connections also let you ask the agent to read or change its threshold:
```text theme={null}
Show me this agent's current payment-approval threshold.
```
```text theme={null}
I want to change this agent's payment-approval threshold. Show me the proposed change before applying it.
```
Confirm the new threshold before the agent updates it. These policy tools are
specific to local MCP connections; do not assume they are available in
ChatGPT or Claude's remote connection.
Changing the threshold does not replace payment review, verification, or a
separate wallet-funding confirmation. See [World ID approval](/autonomy/world-id-approval)
and [Spending grants](/autonomy/spending-grants).
For tool details, see [Local approval policy](/reference/approval-policy).
# Identity verification
Source: https://docs.useagentbank.com/autonomy/kyc
Complete identity checks when they are required for your payment route.
Some fiat payment routes require identity verification, also called KYC.
Ask your agent to check whether your account is ready for the payment you want.
If verification is needed, the agent provides a browser link. Complete the
identity checks there, then return to the conversation and ask the agent to
check the result.
A submitted verification may still be under review, and approval for one
currency does not guarantee access to every route. Wait until the intended
route is available before continuing.
You complete identity verification yourself. It is separate from
[World ID payment approval](/autonomy/world-id-approval).
# Overview
Source: https://docs.useagentbank.com/autonomy/overview
Understand what your agent can do and when AgentBank asks you to act.
You choose which agents can access your account and set your payment-approval
threshold. Before a payment, review its recipient, amounts, and fees.
| Control | What it does |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [Approval threshold](/autonomy/configure-thresholds) | Helps determine whether a payment requires World ID approval. |
| [World ID approval](/autonomy/world-id-approval) | Lets you authorize a payment when AgentBank requests it. |
| [Spending grant](/autonomy/spending-grants) | Gives a remote connection limited permission to fund eligible crypto payments after you choose grant funding. |
| [Identity verification](/autonomy/kyc) | Establishes eligibility for payment routes that require KYC. |
| [Agent verification and gas](/autonomy/agentkit-and-gas) | Verifies the linked wallet for AgentKit and may enable sponsored gas. |
These controls serve different purposes. Signing in does not approve every
payment, and approving a payment does not automatically fund it.
You can [disconnect an agent](/security/account-revocation) when you no longer
want it to have access.
# Spending grants
Source: https://docs.useagentbank.com/autonomy/spending-grants
Set limits for eligible crypto funding through a remote AgentBank connection.
A spending grant is a limited Privy wallet permission for your
[Remote MCP connection](/getting-started/hosted-oauth). It lets the assistant
fund an eligible crypto payment within limits you approve.
## Set up a grant
Ask the assistant to propose a grant. Review its assets and chains,
per-payment limit, total limit over a rolling period, and expiry.
Confirm the proposed limits, then complete activation through the
AgentBank card. A proposed grant cannot spend until you activate it.
After the assistant displays a payment's funding instruction, explicitly
choose whether to pay manually or use a compatible active grant.
```text theme={null}
For this payment, I want to use an active spending grant if one fits its funding requirements.
```
A grant applies only to the current eligible crypto-deposit instruction.
It cannot fund bank, QR, mobile-money, payment-link instructions, or swaps.
Payment review and any World ID approval still apply.
If no compatible grant is available, you can use the payment's manual funding
option. Activating a grant is not permission to fund every future payment.
Builders can find the exact workflow in
[Confirmation and authorization rules](/ai-guides/confirmation-rules).
# World ID approval
Source: https://docs.useagentbank.com/autonomy/world-id-approval
Complete an additional human approval when AgentBank requests it for a payment.
If a payment needs World ID approval, your agent shows an AgentBank approval
link or card.
Open the AgentBank link or card and sign in as the payment owner.
Review the payment and complete its World ID approval before it expires.
Your agent checks the approval and shows the next funding step.
Continue the same payment.
A World ID badge on your account does not replace an approval requested for a
specific payment. Never paste a World ID proof into chat; complete verification
through the approval flow.
For a [payment plan](/payments/payment-plans), one combined approval covers
the reviewed plan when required.
# Changelog
Source: https://docs.useagentbank.com/changelog
Track public AgentBank documentation and MCP contract updates.
## 2026-09-02
* Added a dedicated Partner API section with onboarding, authentication, KYC,
payment workflows, webhook guidance, and endpoint reference pages.
## 2026-07-29
* Init first version of AgentBank document.
# Send between currencies
Source: https://docs.useagentbank.com/exchange/fiat-to-fiat
Pay in one local currency and deliver another to a supported recipient.
> “I want to pay in PHP so my recipient receives 10,000,000 VND. What is the total cost?”
## What to provide
Tell your assistant the currency you will pay in, the destination currency and
country, and either your spending amount or the exact amount the recipient
should receive. Choose a saved recipient or provide the requested payment details.
## Review and pay
Your assistant checks whether a supported conversion is currently available.
This journey uses crypto between the two local currencies; you should see that
conversion in the quote, together with both amounts, all fees and their
currencies, the full recipient details, and the expiry.
Confirm the complete payment and finish World ID approval if required. Then
follow the bank or other fiat payment instructions shown for this payment.
You do not need to send a separate crypto transfer to complete the conversion.
Ask your assistant to track the payment until AgentBank reports completion.
Finishing the first conversion or sending the bank transfer does not by itself
mean the recipient has been paid.
Fund only the current fiat instruction, once. Do not separately fund the
recipient-side payout or send again while payment detection is pending.
See [Payment status and tracking](/payments/track-payments) for the next step.
Builders: see the [route reference](/reference/tools/estimate-payment).
# Overview
Source: https://docs.useagentbank.com/exchange/overview
Compare costs or convert between supported currencies and crypto assets.
Ask your assistant what you can receive for a chosen amount, or how much it
will cost to receive an exact amount. It checks current availability before
offering a quote; asking for a quote does not move money or reserve a rate.
Compare what you pay and receive after all fees.
Exchange supported crypto assets on the same network.
Pay in one local currency and deliver another to your recipient.
To buy crypto with money from your bank, see [Add money](/money-in/add-money).
To pay a bank recipient from crypto, see [Send money to a bank account](/money-out/bank-payout).
# Quotes and rates
Source: https://docs.useagentbank.com/exchange/quotes-and-rates
Understand what you will pay and receive before deciding to proceed.
> “Compare the available options for sending 1,000 PHP to VND. Which gives my recipient the most after fees?”
Tell your assistant the source and destination currencies or crypto assets,
any relevant network, and either how much you want to spend or exactly how
much you want the recipient to receive. You can also state a preference, such
as the lowest total cost.
## Compare the complete quote
* What you will pay and what the recipient or wallet will receive.
* Every percentage or flat fee, including which currency it is charged in.
* The full conversion route, including any additional conversion.
* The payment method and any verification or eligibility requirements.
* The expiry: the time by which the quoted terms need to be used.
A broad rate comparison is only indicative. Ask for an amount-specific quote
before deciding to pay. Providers are not identified by name; compare the
available payment outcomes rather than requesting a named provider.
A quote is information, not a reservation, payment, or guarantee. If it expires
or your payment details change, review a fresh quote. Your assistant must show
the final recipient and complete terms and get your explicit confirmation
before creating the payment.
Builders: see the [quote reference](/reference/tools/estimate-payment).
# Swap crypto
Source: https://docs.useagentbank.com/exchange/same-chain-swaps
Exchange supported crypto assets on the same network.
> “What would I receive if I swapped 100 USDC for another supported token on the same network?”
Tell your assistant which asset you want to spend, which asset you want to
receive, the network, and your amount. Both assets must be supported on the
same network; this journey does not move assets between networks.
Check the amount you will spend or its maximum, the amount you will
receive, all fees and their currencies, your linked wallet, the network,
and the expiry. A quote does not move money or reserve a rate.
Confirm the reviewed swap. Complete World ID approval if required, then
follow the current signing instruction.
A local assistant asks you to explicitly confirm the crypto action. In a
hosted client, you sign through the first-party Privy page that opens.
Spending grants cannot fund swaps.
Ask your assistant to track the existing payment until AgentBank reports
completion. A wallet receipt alone is not the final payment result.
If signing or submission appears interrupted, ask your assistant to check the
existing payment before trying again. Do not start another swap while its
outcome is uncertain.
Builders: see the [wallet execution reference](/reference/tools/execute-payment-instruction).
# Local authorization flow
Source: https://docs.useagentbank.com/getting-started/authentication
Connect a local MCP installation to your AgentBank account and bound Privy wallet.
```mermaid theme={null}
sequenceDiagram
participant User
participant Agent
participant MCP
participant Browser
participant Core
Agent->>MCP: whoami
MCP-->>Agent: MISSING_CREDENTIAL
Agent->>MCP: begin_agent_onboarding
MCP-->>Agent: authorization_url + enrollment_id
Agent-->>User: Connect to your AgentBank Account
User->>Browser: Sign in and authorize
Browser->>Core: Complete account and Privy authorization
Agent->>MCP: wait_for_agent_onboarding(enrollment_id)
MCP->>Core: Poll and finalize
MCP-->>Agent: authenticated + wallet bound
```
## What your agent should do
1. Call `whoami` when AgentBank work begins.
2. If it receives `MISSING_CREDENTIAL`, call `begin_agent_onboarding` once.
3. Show the returned authorization URL.
4. Immediately call `wait_for_agent_onboarding` with the same enrollment ID.
5. If polling times out while still pending, reuse that enrollment ID.
6. Verify `privy_authorized`, `wallet_bound`, and `authenticated`.
7. Check identity, scopes, account readiness, and wallets.
If an existing installation returns `UNAUTHENTICATED` because its session
expired, call `relogin` once and retry the original operation. Do not begin a
new onboarding flow for an expired session.
Credential-store errors such as `CREDENTIAL_PROTECTOR_LOCKED`,
`CREDENTIAL_STORE_CORRUPT`, or `CREDENTIAL_PROFILE_MISMATCH` require the
returned operating-system or profile remediation. Preserve the installation
instead of replacing it.
Never paste a private key, seed phrase, AgentBank token, Privy token,
authorization key, or World ID proof into chat or support.
## Disconnect an agent
`revoke_agent` invalidates the connected installation and clears its local
credential. It requires explicit user confirmation.
Hosted OAuth connections use a different setup and revocation path. See
[Remote MCP](/getting-started/hosted-oauth).
# Connect your agent
Source: https://docs.useagentbank.com/getting-started/connect-your-agent
Configure AgentBank MCP for Codex, Claude Code, Claude Desktop, OpenClaw, or Hermes.
Use this setup for an agent running on your device. It connects to production
by default. To try mock tokens first, see [Environment](/getting-started/environment).
For ChatGPT or Claude's remote connector, use the
[Remote MCP guides](/getting-started/hosted-oauth).
## Install the connection
The local package uses Node.js and `npx`. Choose your client:
```bash theme={null}
codex mcp add agentbank -- npx -y agent-bank-mcp@latest
```
```bash theme={null}
claude mcp add agentbank -- npx -y agent-bank-mcp@latest
```
On macOS, edit:
```text theme={null}
~/Library/Application Support/Claude/claude_desktop_config.json
```
```json theme={null}
{
"mcpServers": {
"agentbank": {
"command": "npx",
"args": ["-y", "agent-bank-mcp@latest"]
}
}
}
```
Preserve other `mcpServers` entries, fully quit Claude Desktop, and reopen it.
Add the server under `mcp.servers` in `~/.openclaw/openclaw.json`:
```json5 theme={null}
{
mcp: {
servers: {
agentbank: {
command: "npx",
args: ["-y", "agent-bank-mcp@latest"],
},
},
},
}
```
Then verify:
```bash theme={null}
openclaw mcp doctor agentbank --probe
```
```bash theme={null}
hermes mcp add agentbank --command npx --args -y agent-bank-mcp@latest
```
Run `/reload-mcp` to load the connection.
## Authorize your account
Restart or reload the client, then ask:
```text theme={null}
Help me connect this agent to my AgentBank account. Do not create a payment.
```
Open the **Connect to your AgentBank Account** link. Sign in and complete the
account and wallet authorization in your browser, then return to your agent.
Confirm that it shows the expected account and wallet.
If authorization is still pending, ask the agent to check the existing setup.
Do not paste wallet keys, sign-in tokens, or World ID proofs into chat.
## Install the skill and start
Follow [Install skill](/getting-started/install-the-skill), then ask the agent
to check that AgentBank is ready. Continue with
[Your first payment](/getting-started/first-payment).
If the connection is missing, check Node.js, `npx`, and the client configuration,
then restart or reload the client. For other problems, see
[Troubleshooting](/support/troubleshooting).
# Environment
Source: https://docs.useagentbank.com/getting-started/environment
Try AgentBank with mock tokens in staging or use real funds in production.
| Environment | App | Funds |
| ----------- | ---------------------------------------------------------- | --------------------------------------------- |
| Staging | [staging.agentbank.world](https://staging.agentbank.world) | Mock tokens with no real-world monetary value |
| Production | [app.useagentbank.com](https://app.useagentbank.com) | Real value through supported payment routes |
## Staging
Use staging to practice adding money, sending payments, and exchanging supported
assets. Ask your agent:
```text theme={null}
Help me add mock tokens to my AgentBank staging wallet, then show me the balance.
```
Your agent finds a supported fiat-to-crypto route and presents it for review.
Once created, the supported staging on-ramp completes automatically.
No real bank transfer, QR payment, or faucet is required.
After the mock tokens arrive, you can try other supported staging payments.
For Codex, use:
```bash theme={null}
codex mcp add agentbank \
--env PROTOCOL_BASE_URL=https://staging-protocol.agentbank.world \
--env APP_BASE_URL=https://staging.agentbank.world \
-- npx -y agent-bank-mcp@latest
```
Other local clients use the same environment values. See
[Connect your agent](/getting-started/connect-your-agent).
These settings apply to the local MCP package.
## Production
The standard [local MCP installation](/getting-started/connect-your-agent)
defaults to production. Production payments use real funds and may become
irreversible after funding.
Before your first payment, confirm your account and wallet, review your
[approval threshold](/autonomy/configure-thresholds), and complete any required
identity checks. Review the recipient, amounts, fees, and expiry before
confirming. Follow [Your first payment](/getting-started/first-payment).
# Your first payment
Source: https://docs.useagentbank.com/getting-started/first-payment
Ask for a payment, review the quote, approve it, and track the result.
Start in [AgentBank chat](https://app.useagentbank.com) or with a
[connected assistant](/getting-started/quickstart).
```text theme={null}
Help me send money to a bank account. Show me how much I will pay, how much they will receive, and all fees before I confirm.
```
Tell the agent the currencies, amount, and destination country. Say whether
you want to send a specific amount or have the recipient receive a specific
amount. The agent checks availability and asks for any missing details.
Choose a saved recipient or provide the requested bank, wallet, or QR
details. Review the recipient, amount sent, amount received, fees, payment
route, and quote expiry. An estimate does not move money.
Complete World ID approval if requested. Then follow the payment's funding
instructions or confirm the supported wallet action. Opening an instruction
or approving a payment does not by itself fund it.
Ask the agent to track the payment until AgentBank confirms completion.
If the payment is still pending, continue tracking the same payment.
If the quote changes or expires, review the new amounts and fees before
confirming again. Bank transfers and crypto transactions may become
irreversible after funds move.
See [Payment status and tracking](/payments/track-payments) for pending payments,
or [Cancel or correct a payment](/payments/cancel-or-correct) if details need to change.
# Remote MCP
Source: https://docs.useagentbank.com/getting-started/hosted-oauth
Connect AgentBank to ChatGPT or Claude with browser sign-in and interactive payment cards.
Use AgentBank from ChatGPT or Claude to collect payments, exchange currencies,
send money, and track the result. Remote MCP connects your assistant to
AgentBank online; no local MCP package is needed.
## Connect your account
Use this server URL in your client's connection settings:
```text theme={null}
https://mcp.useagentbank.com
```
Add the MCP connection and sign in to AgentBank.
Add the remote connector and sign in to AgentBank.
The browser sign-in uses OAuth. Review the requested permissions and connect
the AgentBank account you want the assistant to access.
## Start a conversation
```text theme={null}
Check my AgentBank account and help me prepare a payment. Show me the recipient, amounts, and fees before I confirm.
```
Your assistant can present quotes, payment and plan approvals, funding
instructions, and progress in interactive cards. Follow
[Your first payment](/getting-started/first-payment) for the steps you complete,
and [Payment cards](/payments/hosted-payment-cards) if you need to reopen one.
Optional [spending grants](/autonomy/spending-grants) let you authorize limited
crypto funding. They require separate activation and an explicit funding choice.
To stop access, [disconnect AgentBank](/security/account-revocation).
To use AgentBank's own agent without connecting another assistant, open
[AgentBank chat](https://app.useagentbank.com).
# Install skill
Source: https://docs.useagentbank.com/getting-started/install-the-skill
Give your agent the instructions for setting up and using AgentBank.
The AgentBank skill teaches your agent how to use AgentBank's tools. Use it
with your [local agent setup](/getting-started/connect-your-agent).
## Install skill
```bash theme={null}
npx skills add theagentbank/skills
```
## Or ask your agent to read it
```text theme={null}
Read https://useagentbank.com/SKILL.md and follow instructions to setup and use AgentBank
```
An agent may read the skill only for the current session unless its client
saves it. The skill provides instructions; the MCP connection and browser
sign-in give the agent access to your account.
After setup, ask:
```text theme={null}
Check that AgentBank is connected and ready to use.
```
# Quickstart
Source: https://docs.useagentbank.com/getting-started/quickstart
Choose how you want to use AgentBank, connect your account, and make your first request.
## Choose how to use AgentBank
| Use AgentBank with | What to set up |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [AgentBank's own chat](https://app.useagentbank.com) | Sign in and start chatting. No external agent or installation needed. |
| [ChatGPT](/remote-mcp/chatgpt) | Add the Remote MCP connection and sign in to AgentBank. |
| [Claude](/remote-mcp/claude) | Add the remote connector and sign in to AgentBank. |
| [Your own agent](/getting-started/connect-your-agent) | Connect the local MCP and install the AgentBank skill for Codex, Claude Code, Claude Desktop, OpenClaw, or Hermes. |
Claude Desktop supports both a remote connector and a local MCP setup.
Choose the remote connector for the browser-based sign-in flow; use the local
setup when you want an installation managed on your device.
## Make your first request
Once connected, ask:
```text theme={null}
Check my AgentBank account and wallet. Tell me if I need to finish any setup before making a payment.
```
Confirm that the connected account is yours. If verification or wallet setup
is needed, follow the browser instructions provided by AgentBank.
Then ask for an estimate, for example:
```text theme={null}
I'd like to send money to a bank account. Help me check the available options and fees before I confirm.
```
Follow [Your first payment](/getting-started/first-payment) for the review,
approval, and funding steps, or browse [Example prompts](/ai-guides/conversation-patterns).
## Try it with mock tokens
Use [Environment](/getting-started/environment) to try staging before moving
real money. The standard local installation defaults to production.
# AgentBank
Source: https://docs.useagentbank.com/index
Collect payments, exchange currencies, and send money to bank accounts worldwide.
AgentBank connects AI agents to supported fiat and crypto payment routes.
Tell the agent what you want to do, review the amounts and fees, and complete
any required approval or funding step.
## Use the hosted AgentBank agent
Open [app.useagentbank.com](https://app.useagentbank.com), sign in, and chat
directly with AgentBank's agent. You do not need another AI agent, an MCP
connection, or a skill installation.
Start a conversation with the AgentBank agent.
Prefer your own assistant? [Connect ChatGPT, Claude, or a local agent](/getting-started/quickstart).
## What you can do
Add funds to your wallet or collect a payment from someone else.
Send supported crypto value to a bank recipient.
Swap supported crypto or convert between fiat currencies.
Review several payments together and track each one separately.
Availability depends on the currencies, amount, destination, and your account's
verification. Your agent checks the available route and presents a quote before
you confirm.
## You remain in control
Your wallet is tied to your login and uses Privy wallet infrastructure. You
authorize which agents can use it and set your payment-approval threshold.
Some payments require an additional World ID approval; crypto funding can
require a separate confirmation.
AgentBank does not take custody of your wallet funds. Payment and banking
partners may receive or process funds while completing a supported route.
Read [Autonomy and human control](/autonomy/overview) to understand approvals,
or [Your first payment](/getting-started/first-payment) to get started.
You can also [try staging with mock tokens](/getting-started/environment#staging).
## For AI agents
* **Remote MCP:** `https://mcp.useagentbank.com` (OAuth 2.1 with PKCE). [Connection guide](/getting-started/hosted-oauth).
* **Local MCP:** `npx -y agent-bank-mcp@latest` ([setup](/getting-started/connect-your-agent))
* **Skill:** [https://useagentbank.com/SKILL.md](https://useagentbank.com/SKILL.md)
* **Docs index:** [https://docs.useagentbank.com/llms.txt](https://docs.useagentbank.com/llms.txt)
The MCP server listed in this site's `/.well-known/mcp.json` is documentation
search only. Payments go through the AgentBank MCP above.
## For builders
Use the [MCP reference](/reference/mcp-overview) to integrate AgentBank with an
agent, or the [Partner API](/partner-api) to build payments for your own end users.
# Architecture
Source: https://docs.useagentbank.com/introduction/architecture
Understand the responsibility boundaries between the user, agent, MCP, Core, wallet, and payment rails.
```mermaid theme={null}
flowchart LR
U["User"] --> A["AI agent"]
A --> M["AgentBank MCP"]
M --> C["AgentBank Protocol Core"]
C --> Q["Quote and payment services"]
C --> W["Privy wallet infrastructure"]
C --> R["Payment rails and settlement partners"]
R --> B["Bank or local payment destination"]
U --> P["AgentBank browser action"]
P --> C
P --> I["Privy, World ID, KYC, or fiat action"]
```
| Layer | Responsibility |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| User | Connect the account, set the approval threshold, and complete required browser actions |
| AI agent | Understand the request, call MCP tools, present material details, and track status |
| AgentBank MCP | Restore a local installation or authenticate a hosted OAuth connection, then expose its high-level tools and resources |
| Protocol Core | Enforce authorization, lock routes, issue instructions, verify execution, and store durable state |
| Privy | Provide the AgentBank wallet infrastructure |
| World ID / AgentKit | Provide payment-specific human authorization and verified-agent capabilities |
| KYC provider | Verify eligibility for gated fiat markets |
| Payment rails | Collect or deliver fiat for supported routes |
A successful on-chain receipt is not necessarily final payment completion.
Always use `get_payment` as the authoritative durable status.
# Core concepts
Source: https://docs.useagentbank.com/introduction/core-concepts
Learn AgentBank accounts, wallets, assets, routes, payments, identity, scopes, and idempotency.
## Account owner and connected agent
The **account owner** signs in to AgentBank and authorizes a local installation
or hosted OAuth connection. Each **connected agent** has its own scopes and
connection-scoped payment history. Local installations also have a protected
local credential profile.
## AgentBank wallet
Authorization makes the user's bound Privy wallet available through the
connection's supported tools. Wallet tools return public wallet information
and balances; they never expose a private key or seed phrase.
## Assets and amounts
Crypto assets use a ticker and chain:
```json theme={null}
{ "type": "crypto", "ticker": "USDC", "chain": "worldchain" }
```
Fiat assets use a currency symbol and no chain:
```json theme={null}
{ "type": "fiat", "symbol": "VND" }
```
Human-facing amounts are decimal strings. `exact_source` fixes the amount sent;
`exact_destination` fixes the amount received and may return a source ceiling.
## Quote, estimate, and durable payment
* A **quote-book offer** is anonymous route discovery.
* An **estimate** previews a complete route but is ephemeral and has no ID.
* A **durable payment** begins at `create_payment` and survives MCP restarts.
* A **payment instruction** is the current Core-owned action for that payment.
## Routes and settlement assets
A direct route has one step. Fiat-to-fiat and some token-to-fiat routes use two
steps joined by an explicit crypto **settlement asset**. The agent must choose
that common asset from live pairs; Core does not currently auto-plan it.
## Identity mechanisms
* **Browser authorization** connects the agent and wallet.
* **KYC** determines eligibility for supported fiat markets.
* **World ID payment authorization** approves a payment when Core returns
`approval_required`.
* **AgentKit verification** verifies the agent wallet and may enable sponsored
gas where supported.
A hosted **spending grant** is a separate bounded Privy permission for funding
the current compatible crypto-deposit instruction. It does not replace payment
review or World ID authorization.
## Request IDs
Mutating tools use stable request IDs for idempotency. Reuse an ID only for the
same logical request and identical payload. Changed details require a new ID.
# Add money to your wallet
Source: https://docs.useagentbank.com/money-in/add-money
Pay in a supported local currency and receive crypto in your AgentBank wallet.
Ask your assistant to turn money from your bank into a supported crypto asset
in your linked AgentBank wallet.
> “I want to add money to my AgentBank wallet using PHP and receive USDC. What will it cost?”
## What to provide
* The currency you will pay in.
* Either the amount you want to spend or the amount of crypto you want to receive.
* The crypto asset and network you want to use. If you are unsure, ask your assistant to explain the available choices.
Your assistant checks your linked wallet, account readiness, and currently
available conversions. Availability depends on the currency, asset, network,
amount, and any required verification.
Check what you will pay, what your wallet will receive, all fees and their
currencies, the wallet and network, the conversion route, and the expiry.
A quote does not reserve a rate or move money.
Confirm the reviewed details. Complete World ID approval if requested.
Your assistant then helps you open the payment instructions.
Follow the bank or QR instructions provided for this payment, including
the exact amount and any required reference. Opening instructions or
approving the payment does not itself send money.
Ask your assistant to track the payment until AgentBank reports it
completed. On a local connection, you can also ask to see your updated
wallet balance.
If your bank payment is still being detected, keep tracking the existing
payment. Do not send the money again or start another payment.
Trying AgentBank without real money? See [Environment](/getting-started/environment).
If someone else will pay, use [Collect from another payer](/money-in/collect-from-a-payer).
Building an integration? See the [payment reference](/reference/tools/create-payment).
# Collect from another payer
Source: https://docs.useagentbank.com/money-in/collect-from-a-payer
Create and track a one-time collection that someone else can pay.
Use this when someone else will pay in a supported local currency and you want
to receive crypto in your linked AgentBank wallet.
> “I need to collect 2,000 PHP from a customer and receive USDC in my AgentBank wallet.”
## What to provide
Tell your assistant the payer's currency, the amount to collect or the amount
you want to receive, and your chosen crypto asset and network. Your assistant
checks which options are currently available.
## Review, share, and track
1. Review the payer's amount, the crypto you will receive, all fees and their currencies, your destination wallet, the route, and the expiry.
2. Confirm the collection and complete World ID approval if required.
3. In a hosted connection such as ChatGPT or Claude, ask for a shareable payment link if one is available. Otherwise, or on a local connection, share the bank or QR instructions provided for this specific payment.
4. Have the payer follow those instructions. A link or instruction does not itself move money.
5. Ask your assistant to track the collection. Treat it as complete only when AgentBank reports completion.
Links are not available for every payment. Do not reuse an old payment's bank
details or QR code for a new collection, and do not ask the payer to pay again
just because detection is pending.
AgentBank can report whether the collection was paid, but your assistant
cannot identify who paid it. A paid collection is not customer identity
verification.
See [Payment status and tracking](/payments/track-payments) for pending payments.
Builders can find the connection-specific capabilities in the
[MCP reference](/reference/mcp-overview).
# Overview
Source: https://docs.useagentbank.com/money-in/overview
Choose how to receive crypto in your AgentBank wallet.
Pay in a supported local currency and receive crypto in your linked AgentBank
wallet. Choose the guide based on who is paying.
Use your own money to buy crypto for your wallet.
Give someone else payment instructions or an available shareable link.
Your assistant checks live availability and shows the amount, fees, destination,
and expiry before you confirm. AgentBank can report whether a collection was
paid, but your assistant cannot identify its payer.
# Send money to a bank account
Source: https://docs.useagentbank.com/money-out/bank-payout
Use supported crypto to pay a bank recipient in local currency.
> “Send my saved recipient enough USDC for them to receive 1,000,000 VND in their bank account.”
## What to provide
* The crypto asset and network you want to pay from.
* Either your spending amount or the exact amount the recipient should receive.
* The destination currency and country.
* A saved recipient, bank details, or a supported payment QR code.
Your assistant checks the available conversion and asks for any missing
recipient information. If several saved recipients match, choose the right
one before continuing.
Check both amounts, every fee and its currency, the bank recipient,
conversion route, network, and expiry. Some crypto assets need an additional
conversion before they can be paid out. That conversion and its costs must
be included in your review. If no supported route is available, the
payment cannot proceed.
Confirm the complete payment. Complete World ID approval if requested.
Your assistant must not silently change your asset, network, recipient,
or the amount you chose to spend or receive.
Follow the current wallet instruction. A local assistant asks for explicit
confirmation before sending crypto. In a hosted client, use the funding or
signing experience shown; eligible crypto deposits may also offer a
separately confirmed spending grant.
Ask your assistant to track the payment until AgentBank reports completion.
A successful crypto transfer alone does not mean the bank recipient was paid.
Check the bank details carefully: a funded transfer may be irreversible. If
the route includes an additional conversion, follow only the current funding
instruction; do not send a second transfer to fund the payout separately.
See [Manage recipients](/money-out/manage-recipients) or
[Cancel or correct a payment](/payments/cancel-or-correct) if details are wrong.
Builders can find route mechanics in the [quote reference](/reference/tools/estimate-payment).
# Manage recipients
Source: https://docs.useagentbank.com/money-out/manage-recipients
Choose a saved recipient or safely add new bank, QR, or wallet details.
> “Show my saved recipients so I can choose who to pay.”
## Choose someone you have paid before
Ask your assistant to find a saved recipient by name or familiar details.
Review the destination before using it. If more than one record matches,
your assistant should ask you to choose rather than guess.
## Add a new recipient
Provide the bank or wallet details your assistant requests, paste labeled bank
information, or share a supported payment QR code or QR image. The required
details depend on the available payment method. Your assistant checks the
details and asks for anything missing or invalid.
A QR image must contain a readable QR code; a text-only screenshot cannot be
read as bank details. Paste the text instead. Before paying, review the
validated recipient along with the quote. Saving a recipient does not send money.
## Change saved details
> “My recipient has a new bank account. Help me replace their saved details.”
Your assistant shows the replacement details and asks for your confirmation.
The replacement is a new saved record; the old record is not automatically
removed or disabled. Check which record you select for future payments.
Changing a saved recipient does not correct a payment already in progress.
See [Cancel or correct a payment](/payments/cancel-or-correct) for the supported
options.
Builders: see the [recipient reference](/reference/tools/create-recipient).
# Overview
Source: https://docs.useagentbank.com/money-out/overview
Pay a bank recipient using supported crypto.
Tell your assistant who should receive money, in which currency, and how much
you want to spend or have them receive. It checks available conversions from
your crypto and helps you review the bank details.
Review the complete conversion cost, fund the payment, and track delivery.
Choose a saved recipient or add bank, QR, or wallet details.
Bank transfers may become irreversible after funding. Check the full recipient
details, amounts, fees, and expiry before confirming.
# API reference
Source: https://docs.useagentbank.com/partner-api/api-reference
Endpoint-by-endpoint reference for discovery, signed partner, and merchant portal APIs.
Set `AGENTBANK_BASE_URL` using [Environments](./environments). All endpoint
paths are relative to that host; credentials and resources are isolated by environment.
## Use the workflow first
Begin with the [Quickstart](./quickstart) for the complete integration sequence,
then use these endpoint pages for request and response details.
## Endpoint groups
Every endpoint has its own page with authentication, path/query parameters,
example request, and example response.
| Group | Use it for |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Discovery](./reference/discovery/currencies) | Active currencies, live fiat instruments, recipient schemas, and curated bank names. These routes are public and work for both personal and partner clients. |
| [Signed Partner API](./reference/partner/create-end-user) | KYC, recipient previews, payment estimates, payment lifecycle reads, and cancellation. Every request is Ed25519-signed. |
| [Merchant Portal API](./reference/portal/login) | Portal login, payment-history reads, and webhook endpoint management. |
## Content conventions
* Use `Content-Type: application/json` for bodies.
* Send and sign the exact UTF-8 JSON bytes.
* Timestamps returned by the B2B objects may be strings containing Unix
milliseconds; payment `created_at` and `updated_at` are ISO timestamps.
* Preserve all opaque IDs (`mp_`, `mpk_`, `peu_`, `pay_`, `mwe_`) as strings.
* Treat fields documented as provider-generated, especially `payment_instruction`
and `timeline`, as read-only.
# Authentication
Source: https://docs.useagentbank.com/partner-api/authentication
Ed25519 request signing for the Partner API and JWT login for the portal API.
## Signed Partner API
Every request to `/v1/partner/*` uses the merchant Ed25519 key pair. This
includes end-user KYC and all payment operations, including signed reads.
| Header | Value |
| ------------------------ | ------------------------------------------------------ |
| `x-agentbank-partner-id` | Partner ID returned during onboarding (`mp_...`) |
| `x-agentbank-timestamp` | Unix time in milliseconds, exactly 13 digits |
| `x-agentbank-nonce` | Fresh, unique request nonce; maximum 256 characters |
| `x-agentbank-signature` | Base64 Ed25519 signature of the canonical request |
| `x-correlation-id` | Optional merchant correlation ID, up to 256 characters |
Sign the exact raw JSON bytes you send. Do not serialize again after signing.
The canonical request is:
```text theme={null}
agentbank-ed25519-v1
METHOD
pathAndQuery
timestamp
nonce
SHA256(rawBody)
```
`pathAndQuery` includes the leading slash and query string, if any. The body
hash is lowercase hexadecimal SHA-256. A `GET` with no body uses the hash of an
empty byte string.
```js theme={null}
import { createHash, createPrivateKey, randomUUID, sign } from 'node:crypto';
const rawBody = Buffer.from(JSON.stringify(payload));
const timestamp = String(Date.now());
const nonce = randomUUID();
const pathAndQuery = '/v1/partner/payments';
const canonical = [
'agentbank-ed25519-v1',
'POST',
pathAndQuery,
timestamp,
nonce,
createHash('sha256').update(rawBody).digest('hex')
].join('\n');
const signature = sign(null, Buffer.from(canonical), createPrivateKey(privateKeyPem))
.toString('base64');
```
AgentBank verifies the timestamp within its configured acceptance window and
stores a successful nonce for that window. Reusing a nonce, signing a different
path, or sending a body different from the signed bytes fails authentication.
Synchronize your backend clock and generate the nonce immediately before send.
The partner ID selects its sole active public key but is not a bearer secret:
the corresponding private Ed25519 key is still required to make every valid request.
## Merchant portal JWT
The portal API is separate. Exchange provisioned credentials at:
```text theme={null}
POST /v1/merchant/auth/login
```
```json theme={null}
{"username":"example_merchant","password":"replace-with-secret"}
```
The response contains `access_token`, `token_type: "Bearer"`, `expires_at`,
and `merchant_partner_id`. Send it as:
```http theme={null}
Authorization: Bearer
```
Portal JWTs may manage webhook endpoints and read only that merchant's payment
history. They cannot submit KYC, create payments, cancel payments, or invoke a
funding action. Use the signed Partner API for those operations.
Portal credential reprovisioning invalidates existing portal JWTs. On a `401`,
log in again rather than retrying a stale token.
# End-user KYC
Source: https://docs.useagentbank.com/partner-api/end-user-kyc
Create a Core-issued end user with full KYC, then submit versioned partial updates.
All KYC routes use the signed Partner API. KYC belongs to the authenticated
merchant: one merchant cannot read or update another merchant's end users.
## Create an end user
```text theme={null}
POST /v1/partner/end-users
```
The body is `{ "kyc": }`. A create
is complete, not a patch. AgentBank generates and returns `end_user_id`.
Never send an `end_user_id`, `merchant_kyc_reference`, or provider user ID.
### Required KYC structure
| Section | Required fields |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version` | Exactly `partner_end_user_kyc_v1` |
| `attestation` | `collected_at`, `verified_at` as ISO 8601 timestamps |
| `person` | `first_name`, `last_name`, `date_of_birth`, `gender`, `nationality`, `country_of_residence`, `occupation` |
| `contact` | `email`, `phone_e164` |
| `residential_address` | `line1`; `line2`, `city`, `state_or_province`, `postal_code`, and `country` are optional |
| `identity_document` | `type`, `number`, `issuing_country`, `issued_on`, `expires_on` |
| `artifacts` | `document_front`, `selfie_with_document`, `kyc_report_pdf`, and `document_back_not_applicable`; supply `document_back` when that boolean is `false` |
Allowed values:
* `person.gender`: `male`, `female`, `other`, or `unspecified`
* `identity_document.type`: `national_id`, `passport`, or `work_permit`
* country fields: ISO 3166-1 alpha-2 uppercase codes
* phone: E.164 format
Each inline artifact is supplied in the same registration request:
```json theme={null}
{
"content_type": "image/jpeg",
"sha256": "lowercase-hex-sha256-of-decoded-bytes",
"data_base64": "base64-encoded-bytes"
}
```
`document_front`, `document_back`, and `selfie_with_document` accept
supported image formats; `kyc_report_pdf` is `application/pdf`. AgentBank
verifies the content hash, stores the bytes privately, binds them atomically to
the immutable KYC version, and forwards provider-ready KYC downstream as
needed. There is no separate artifact-upload API.
Do not omit documents merely because the base JSON has all biographical fields.
KYC reports and images are accepted in the same signed request so the KYC
version is auditable and complete.
## Create response
The [Create end user reference](./reference/partner/create-end-user) contains
the complete request and response example. Save its generated `end_user_id`
and current `kyc_version`; use [Rail readiness](./rail-readiness) to decide
when that end user can make a payment.
Raw KYC, document numbers, and artifact bytes are never returned.
## Update KYC
```text theme={null}
PUT /v1/partner/end-users/:endUserId/kyc
```
Updates are partial and optimistic-versioned:
```json theme={null}
{
"base_kyc_version": "1",
"kyc": {
"contact": {"phone_e164": "+84999999999"}
}
}
```
Omitted fields retain their base-version values; `null` and unknown fields are
rejected. An artifact update uses the same inline artifact object as create.
Read the latest end-user record before updating and use its `kyc_version` as
`base_kyc_version`. A successful change produces a new immutable version and
may return the end user to provider processing while rail readiness is refreshed.
## Read KYC and readiness
```text theme={null}
GET /v1/partner/end-users/:endUserId
```
The response is a redacted summary, status, KYC version, and rail readiness.
Use it rather than keeping a local copy of raw KYC data.
## Identity and provider handling
Use the AgentBank-issued end-user ID for subsequent operations. Provider
identity resolution is handled by AgentBank; never submit provider identity
keys or provider customer IDs.
# Environments
Source: https://docs.useagentbank.com/partner-api/environments
Sandbox and Production API hosts, isolation, and promotion guidance.
AgentBank has two fully isolated API environments. Select the base URL before
onboarding a merchant or storing any integration state.
| Environment | API base URL | Intended use |
| ----------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| Sandbox | `https://staging-protocol.agentbank.world` | Build, test webhooks, validate KYC integration, and exercise payment flows |
| Production | `https://protocol.useagentbank.com` | Live merchant onboarding and customer payments |
Set `AGENTBANK_BASE_URL` in trusted backend configuration to the selected URL.
Every API path is relative to it: signed Partner routes use `/v1/partner/*`,
portal routes use `/v1/merchant/*`, and public discovery routes use `/api/*`.
## Environment isolation
Sandbox and Production do not share any merchant resource or credential:
* merchant IDs and Ed25519 key registrations
* portal usernames, passwords, and JWTs
* webhook endpoint IDs and HMAC signing secrets
* end-user IDs, KYC versions, rail readiness, payment IDs, and payment history
Register the merchant again in Production, use a Production-only key pair or
securely provisioned Production key, register Production webhook endpoints, and
repeat KYC/payment testing with approved live procedures before go-live.
## Configuration
Do not make the base URL user-controlled. Pin it in trusted backend
configuration and allow only HTTPS outbound traffic to the selected host.
# Errors and idempotency
Source: https://docs.useagentbank.com/partner-api/errors-and-idempotency
Make safe retries, resolve conflicts, and avoid duplicate merchant payments.
Design every caller for retries. Network uncertainty does not mean a payment or
KYC write did not reach AgentBank.
## Error response
Application errors include a machine-readable error object. Integrations should
branch on `error.code`, not on the prose message:
```json theme={null}
{
"error": {
"code": "LIMIT_EXCEEDED",
"message": "This end user already has an active payment (pay_..., funding_required)",
"retryable": false,
"correlation_id": "merchant-correlation-id"
}
}
```
Log the HTTP status, error code, and correlation ID. Redact KYC, passwords,
signature headers, private keys, and webhook secrets.
## Common integration failures
| Condition | Typical outcome | Correct action |
| ---------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Missing/expired timestamp, duplicate nonce, or invalid signature | Authentication/signature error | Create a new signed request with a fresh nonce after fixing clock/key/body handling |
| KYC schema or artifact hash failure | KYC schema error | Correct the exact field or artifact. Do not retry unchanged invalid data |
| Stale `base_kyc_version` | Conflict | Fetch the end user, merge against the latest allowed fields, and submit a new patch |
| Unready rail | Validation/eligibility failure or unavailable estimate | Wait for readiness or use an available corridor |
| Active payment for the end user | `LIMIT_EXCEEDED` | Inspect, complete, cancel, or wait for the active payment; do not create a second order |
| Same payment reference, different body | Idempotency conflict | Keep one reference per economic order. Create a new reference only for a genuinely new order |
| Provider failure after funds moved | Terminal failed payment with `funds_moved: true` | Stop automatic retries and follow your recovery/support procedure |
## Payment idempotency
`merchant_payment_reference` is the durable idempotency key for
`POST /v1/partner/payments`, scoped to the merchant.
* Reuse the same reference with the **same** normalized payment request to get
the original payment view.
* Reuse it with a different payload to receive an idempotency conflict.
* Generate a different reference for a new commercial order, never for a
transport retry of the old one.
* `request_id` is useful merchant correlation metadata but does not replace
`merchant_payment_reference` for payment idempotency.
If a create request times out, first retry the exact same request with the same
merchant payment reference or list/read your merchant payment history. Do not
change the recipient, amount, or reference merely because the first response
was lost.
## KYC retries and versions
Create requires a complete KYC record. The same verified document identity is
not a license to create an unrelated second end user. Keep the returned
`end_user_id`, then use `PUT` with its `base_kyc_version` for updates. On a
version conflict, fetch the latest redacted record and have your verified KYC
source provide a fresh, allowed patch.
## Webhook retries
Webhook delivery is at least once and separate from the API response. A `2xx`
acknowledges the specific delivery. Network errors, `429`, and `5xx` can cause
the same `x-agentbank-delivery-id` to arrive again. Persist that ID before
processing and make downstream state updates idempotent.
Use the payment read endpoint as recovery authority if a webhook is delayed,
unknown, or received after a service restart.
# Funding and tracking
Source: https://docs.useagentbank.com/partner-api/funding-and-tracking
Present funding instructions safely and follow a payment through terminal state.
Payment creation returns an aggregate that explains the next required action.
Use it as the source of truth rather than reconstructing a flow from quotes or
provider assumptions.
## Funding instructions
When `next_action.type` is `fund`, display `payment_instruction` to the end
user or execute it from your merchant-controlled funding wallet.
| Instruction type | What to do |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `bank_transfer` | Show the exact account, beneficiary, reference, and amount |
| `qr` | Present the exact provider QR payload or image |
| `payment_link` | Direct the payer to the returned URL and preserve the expiry |
| `mobile_money` | Follow the returned mobile-money recipient/instruction |
| `crypto_deposit` | Send only the stated asset/amount on the stated chain to the exact address; honor memo and calldata when supplied |
Never change the amount, token, chain, address, memo, reference, or expiry.
Preserve the full `pay_to` object, including token contract and token decimals
when supplied alongside crypto memo or calldata.
For a two-hop fiat-to-fiat payment, fund only the first visible instruction.
The intermediate crypto delivery is internal to AgentBank.
## Poll payment state
```text theme={null}
GET /v1/partner/payments/:paymentId
```
The response has three useful layers:
| Field | Meaning |
| ---------------------------------- | ------------------------------------------------------------------------- |
| `status`, `terminal`, `successful` | The top-level outcome for the merchant order |
| `next_action` | `fund`, `wait`, or `none`, with safe user-facing guidance |
| `hops` | Read-only progress for one or two internal payment legs |
| `timeline` | Detailed provider settlement events, with `hop_index` and `settlement_id` |
Common terminal states are `completed`, `cancelled`, and `failed`.
`funds_moved` tells you whether any funds were moved, which matters for support
and recovery handling. A payment can be non-terminal with `next_action: wait`
while a provider is reconciling it.
When a provider supplies a crypto transaction hash, the relevant timeline entry
contains `tx_hash`. It may be `null` for a fiat event or a provider event with
no on-chain transaction.
## Webhooks and polling together
Use webhooks for prompt state changes and polling for recovery:
1. Verify, deduplicate, and durably store every webhook.
2. Update your local view from the payment snapshot in its `data` payload.
3. For `payment.timeline_step.recorded`, append the new `data.timeline_step` by
`step_id` instead of inventing a new status.
4. On restart, delayed webhook, or uncertain timeout, fetch the payment by ID.
5. Close your order only when `terminal` is `true`; use `successful` to
distinguish a successful terminal completion from a terminal failure.
`payment.created`, `payment.funding_required`, and lifecycle events provide a
complete fresh payment representation. A timeline webhook likewise carries a
fresh snapshot plus the newly observed timeline step.
## Expiry and support
Funding instructions can expire. Before asking the end user to pay, fetch the
payment again and confirm the instruction is still present and not expired. If
funding is late, do not make a replacement payment while the original one is
active; first inspect or cancel the original payment. Include the `payment_id`,
merchant payment reference, and optional `x-correlation-id` in support cases,
but never include KYC bytes, private keys, or webhook secrets.
# AgentBank Partner API
Source: https://docs.useagentbank.com/partner-api/index
Build regulated fiat and crypto payments for your own end users.
The Partner API lets your backend offer payments to verified end users:
fiat to crypto (on-ramp), crypto to fiat (off-ramp), or fiat to fiat through
an intermediate crypto asset. You provide the final recipient; AgentBank
handles routing and returns the funding instruction and payment state.
Partner requests use your merchant Ed25519 key. The separate portal API uses
a JWT for webhook management and payment-history reads. Keep all credentials
in your trusted backend.
## Start here
* [Quickstart](./quickstart): the complete provisioning-to-payment workflow.
* [Environments](./environments): Sandbox and Production base URLs and isolation.
* [Onboarding](./onboarding) and [Authentication](./authentication): credentials and signing.
* [End-user KYC](./end-user-kyc) and [Rail readiness](./rail-readiness): required verification before payment.
* [Payments](./payments) and [Funding and tracking](./funding-and-tracking): payment decisions and lifecycle handling.
* [Portal and webhooks](./portal-and-webhooks): endpoint management and delivery verification.
* [Errors and idempotency](./errors-and-idempotency): safe retries and recovery.
* [API reference](./api-reference): endpoint request and response contracts.
# Onboarding
Source: https://docs.useagentbank.com/partner-api/onboarding
Set up merchant credentials and prepare your backend for the Partner API.
AgentBank activates each merchant before it can call the Partner API. The
merchant generates and owns its Ed25519 key pair; only the public key is shared
with AgentBank.
## Provide these details
Send the following through the approved onboarding channel:
* merchant display name
* Ed25519 public key in PEM SPKI form
* portal username: 3-64 lowercase letters, numbers, dots, underscores, or
hyphens
* initial portal password: 12-256 characters
Keep the private key only in your backend secret manager. Never send it to
AgentBank, embed it in a client application, or commit it to source control.
## Receive and store merchant configuration
After activation, AgentBank sends the following through the approved secure
channel:
* `merchant_partner_id`, for example `mp_...`; send this as
`x-agentbank-partner-id`
* the provisioned portal username and password
Store the merchant ID and private key together in your backend configuration.
Store the portal password separately. The portal password is stored by AgentBank
only as a salted hash.
## Verify access
1. Use the private key and merchant ID to sign a Partner API request
as described in [Authentication](./authentication).
2. Exchange the portal username and password at
`POST /v1/merchant/auth/login`.
3. Register a webhook endpoint before creating KYC records or payments.
## Credential recovery and rotation
Contact AgentBank through the approved support channel to:
* replace portal credentials; this invalidates existing portal JWTs
* rotate the registered Ed25519 public key; keep using the same merchant ID
before sending another signed request
* suspend or restore merchant access
Generate and securely store a replacement key pair before requesting a key
rotation. Do not retry a failed signed request until AgentBank
confirms the rotation is complete.
# Payments
Source: https://docs.useagentbank.com/partner-api/payments
Choose a payment shape, estimate at checkout, and create one merchant order.
The Partner API is semantic: specify what the end user pays and receives,
the amount mode, and the final recipient. AgentBank owns routing and any
intermediate transfers. Follow the [Quickstart](./quickstart) for the full
integration sequence.
Do not send intent IDs, quote IDs, route agreement IDs, hop lists, callback
URLs, registered-recipient IDs, or recipients for internal hops.
## Choose the payment shape
| Shape | Final recipient |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| On-ramp: fiat to crypto | A crypto address on the destination chain |
| Off-ramp: crypto to fiat | A supported fiat payout instrument, such as a QR or bank account |
| Fiat-to-fiat: `on_ramp -> off_ramp` | Only the final fiat recipient; AgentBank supplies the intermediate crypto recipient |
For an on-ramp, put the crypto address in `recipient_fields.address`.
Fiat-to-fiat supports this two-hop shape only. Do not create a separate merchant
payment for the intermediate transfer or request identical source and destination
assets.
Discover live instruments through
[List fiat payment capabilities](./reference/discovery/fiat-payment-capabilities),
not a static currency list alone. Before a fiat payout, use
[Parse QR recipient](./reference/partner/parse-qr-recipient) or
[Verify bank recipient](./reference/partner/verify-bank-recipient), as applicable,
and carry the returned canonical `recipient_fields` into payment creation.
## Estimate before commitment
[Estimate payment](./reference/partner/estimate-payment) owns the quote request
and response examples, including `preferred_rails`. Send the end user and the
supported `on_ramp` or `off_ramp` direction with exactly one of `amount_in` or
`amount_out`.
An estimate filters by end-user readiness but is non-binding. It does not
reserve a route or authorize funds to move. Request it near checkout, then
create the payment when the customer commits.
## Create one commercial order
[Create payment](./reference/partner/create-payment) owns the complete request
and response contract. Supply the merchant end user, your request correlation
ID, durable `merchant_payment_reference`, source and destination assets, amount
mode, and final recipient.
Choose `exact_source` when the payer fixes how much to spend; put that amount in
`source`. Choose `exact_destination` when the customer fixes how much must
arrive; put that amount in `destination`. Amounts are strings.
For a QR recipient, country is normally derived from `qr_content`; an optional
country constraint must match. A direct bank recipient requires `country`.
Never add a client-selected internal rail. Recipient validation happens again
when the payment is created, without using a saved recipient book.
Use one payment reference per economic order and reuse the same body and
reference after an uncertain request. See
[Payment idempotency](./errors-and-idempotency#payment-idempotency).
## Follow the returned payment
The server-generated `payment_instruction` is the funding authority;
`next_action` tells the customer whether to fund or wait. Preserve the issued
amount, asset, destination, chain, memo, reference, calldata, and expiry.
[Funding and tracking](./funding-and-tracking) explains how to present the
instruction and reconcile webhooks with current payment state.
Use [Get payment](./reference/partner/get-payment) for the full current view
and [List payments](./reference/partner/list-payments) for merchant history and
its supported filters. Portal JWT holders can also
[read](./reference/portal/get-payment) and [list](./reference/portal/list-payments)
payments, but cannot create or cancel them.
## Cancellation and active-payment limits
[Cancel payment](./reference/partner/cancel-payment) applies before funding
where the current settlement state permits it. Do not report success until
the returned or subsequently read payment is terminal with `status: "cancelled"`.
Each end user may have only one non-terminal B2B payment, regardless of direction
or hop count. Complete, cancel, or let it reach a terminal state before creating
another. Internal fiat-to-fiat hops are not separate merchant orders.
# Portal and webhooks
Source: https://docs.useagentbank.com/partner-api/portal-and-webhooks
Manage webhook endpoints with a portal JWT and verify durable HMAC deliveries.
The merchant portal API manages webhook endpoints and reads payment history. It
uses a portal JWT, not your Ed25519 signing key.
## Log in
Use [Portal login](./reference/portal/login) to exchange your provisioned
username and password for an `access_token`.
Send the returned token with `Authorization: Bearer ` for every
endpoint on this page.
## Register an endpoint
Call [Create webhook](./reference/portal/create-webhook) with your callback
`url`. The reference contains the request and response example.
Store `signing_secret` before responding to the user. It is returned **only**
by this create response and cannot be read, changed, or recovered later. If it
is lost, register a new endpoint and update your receiver to use the new
secret.
There is no callback URL in end-user KYC or payment requests. Every active
registered endpoint receives a durable delivery for each new merchant event.
New endpoints do not receive a replay of older events.
## Manage endpoints
| Method | Path | Meaning |
| -------- | ----------------------------------- | ----------------------------------------------------------------- |
| `GET` | `/v1/merchant/webhooks` | List active and disabled endpoints owned by the merchant |
| `GET` | `/v1/merchant/webhooks/:endpointId` | Read one endpoint |
| `PATCH` | `/v1/merchant/webhooks/:endpointId` | Replace the URL of an active endpoint: `{ "url": "https://..." }` |
| `DELETE` | `/v1/merchant/webhooks/:endpointId` | Soft-disable the endpoint |
An endpoint cannot be reactivated or edited after deletion. Register a new one
instead. Deleting it does not change its signing secret; it simply stops future
delivery to that endpoint.
## Verify deliveries
AgentBank posts JSON to your endpoint with these headers:
| Header | Meaning |
| ------------------------------- | ---------------------------------------------- |
| `x-agentbank-webhook-id` | Registered endpoint ID |
| `x-agentbank-delivery-id` | Stable identifier for this endpoint delivery |
| `x-agentbank-event-id` | Stable event identifier |
| `x-agentbank-timestamp` | Unix milliseconds when the delivery was signed |
| `x-agentbank-signature-version` | `agentbank-webhook-hmac-sha256-v1` |
| `x-agentbank-signature` | `v1=` |
Read the exact raw UTF-8 body before parsing JSON. The HMAC input is:
```text theme={null}
agentbank-webhook-hmac-sha256-v1
deliveryId
eventId
timestamp
SHA256(rawBody)
```
The HMAC uses SHA-256 and the endpoint's `signing_secret`. Compare the
`v1=` value in constant time. Also enforce a reasonable timestamp window
in your receiver, persist the delivery ID before processing, and return `2xx`
only after durable acceptance.
```js theme={null}
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
const rawBody = request.rawBody; // exact UTF-8 string, not reserialized JSON
const canonical = [
'agentbank-webhook-hmac-sha256-v1',
headers['x-agentbank-delivery-id'],
headers['x-agentbank-event-id'],
headers['x-agentbank-timestamp'],
createHash('sha256').update(rawBody, 'utf8').digest('hex')
].join('\n');
const expected = `v1=${createHmac('sha256', signingSecret)
.update(canonical, 'utf8').digest('hex')}`;
const valid = Buffer.byteLength(expected) === Buffer.byteLength(headers['x-agentbank-signature']) &&
timingSafeEqual(Buffer.from(expected), Buffer.from(headers['x-agentbank-signature']));
```
## Delivery model
The payload has this envelope:
```json theme={null}
{
"event_id": "evt_...",
"event_type": "payment.timeline_step.recorded",
"occurred_at": "...",
"merchant_partner_id": "mp_...",
"aggregate": {"type":"payment","id":"pay_...","sequence":"4"},
"data": {"payment_id":"pay_...","status":"funding_required"}
}
```
Expect the following event families:
* `end_user.kyc.accepted` and `end_user.rail_readiness.updated`
* `payment.created`, `payment.funding_required`, `payment.completed`,
`payment.failed`, `payment.cancelled`, and `payment.updated`
* `payment.timeline_step.recorded`, whose `data.timeline_step` is a newly
observed timeline entry and whose data includes a fresh payment snapshot
Delivery is at least once. Transient network failures, `429`, and `5xx`
responses are retried with backoff. Use `x-agentbank-delivery-id` to
deduplicate; do not assume ordering across endpoints or use a duplicate as a
second payment instruction.
Your endpoint must be publicly reachable over HTTPS. A local development
tunnel must forward to your actual webhook server port, not to a tunnel
inspector page.
# Quickstart
Source: https://docs.useagentbank.com/partner-api/quickstart
The end-to-end path from merchant provisioning to a completed payment.
Use this sequence to integrate the Partner API. Endpoint links provide the
request and response examples; the steps below explain when to call them.
Keep KYC bytes, private keys, QR payloads, and webhook secrets out of prompts,
client logs, and telemetry.
## 1. Provision the merchant and authenticate
Choose the [Sandbox base URL](./environments) and use that environment
consistently for all credentials and resources. Complete [Onboarding](./onboarding):
generate an Ed25519 key pair in your backend, share only its public PEM with
AgentBank, and securely store the returned merchant ID and portal credentials.
Implement [request signing](./authentication) before calling `/v1/partner/*`.
Sign the exact bytes you send and use a fresh nonce for every request, including
signed reads. Keep the private key in your server-side secret manager.
## 2. Register a webhook
[Log in to the portal](./reference/portal/login), then use its `access_token` to
[register a public HTTPS endpoint](./reference/portal/create-webhook). Store the
returned `signing_secret` immediately: it is shown only once.
Implement [delivery verification and deduplication](./portal-and-webhooks)
before creating KYC records or payments. Portal JWTs manage webhooks and read
payment history; they do not authorize Partner API writes.
## 3. Discover available assets and recipient forms
Before rendering a payment form, read the public discovery APIs:
1. [List currencies](./reference/discovery/currencies) for active symbols and decimals.
2. [List fiat payment capabilities](./reference/discovery/fiat-payment-capabilities)
for live directions and final fiat-recipient instruments. Only `off_ramp`
entries carry those recipient fields; an on-ramp ends at a crypto address.
3. [Get payment instrument schemas](./reference/discovery/payment-instrument-schemas)
for QR, direct bank-transfer, and mobile-money fields.
4. [List supported bank names](./reference/discovery/supported-bank-names)
when the customer selects direct bank transfer.
Discovery is form metadata, not proof of an end user's readiness or a guarantee
that a quote will remain available.
## 4. Create or refresh the end user
Call [Create end user](./reference/partner/create-end-user) with a complete
`partner_end_user_kyc_v1` record and inline artifacts. Follow the required
fields and artifact rules in [End-user KYC](./end-user-kyc). Do not send an
end-user ID, merchant KYC reference, or provider user ID.
Persist the returned `end_user_id`. For a correction, read the end user and
[update KYC](./reference/partner/update-end-user-kyc) with the latest
`base_kyc_version`. Do not create a second end user merely because a request
timed out; follow [KYC retry guidance](./errors-and-idempotency#kyc-retries-and-versions).
## 5. Wait for the required fiat rails
Poll [Get end user](./reference/partner/get-end-user) or process
`end_user.rail_readiness.updated`. Continue only when the fiat currencies
required by the payment have `rail_readiness[].state: "available"`.
KYC acceptance alone is insufficient: provider forwarding is asynchronous, and
an end user can be ready for one currency but not another. See
[Rail readiness](./rail-readiness) for pending, unavailable, and expired states.
## 6. Preflight the final fiat recipient
Skip this step for an on-ramp whose final recipient is a crypto address.
* For a QR payout, call [Parse QR recipient](./reference/partner/parse-qr-recipient)
with `qr_content`. Do not send `rail` or `end_user_id`. Supply `country` only
as an independent constraint; a mismatch with the detected country is rejected.
* For a direct bank payout, call [Verify bank recipient](./reference/partner/verify-bank-recipient)
with `end_user_id`, `country`, and the required bank details. Do not send `rail`.
Use the returned canonical `recipient_fields` unchanged, including resolved
recipient details. Preflight does not store a recipient, reserve liquidity, or
move funds. QR parsing does not replace the end-user readiness check.
## 7. Estimate immediately before checkout
Call [Estimate payment](./reference/partner/estimate-payment) with the same
end user and economic direction. The endpoint supports `on_ramp` and `off_ramp`
estimates and filters out rails that are not ready for that end user.
An estimate is non-binding: it neither reserves liquidity nor authorizes
settlement. See [Payments](./payments) for the supported payment shapes.
## 8. Create one payment when the customer commits
Call [Create payment](./reference/partner/create-payment) with the end user,
source and destination assets, amount mode, and final `recipient_fields`.
For fiat-to-fiat, supply only the final fiat recipient, never a crypto bridge
address or a recipient for an internal hop.
Use one durable `merchant_payment_reference` per commercial order. If a request
times out, reuse the identical body and reference with a fresh signature and
nonce; changing the body under the same reference causes an idempotency
conflict. See [Errors and idempotency](./errors-and-idempotency).
Do not request identical source and destination assets or create parallel
active payments for one end user. Complete, cancel, or wait for the existing
payment to become terminal before starting another.
## 9. Fund only as instructed
Read `next_action` and `payment_instruction` from the response. When instructed
to fund, display or execute exactly the issued asset, amount, account/address,
chain, memo, reference, QR, calldata, and expiry. Do not reconstruct an
instruction from a quote or substitute a familiar account.
When `next_action.type` is `wait`, do not ask the payer to pay again. For
fiat-to-fiat, fund only the first visible instruction; AgentBank handles the
intermediate transfer. See [Funding and tracking](./funding-and-tracking).
## 10. Track to a terminal outcome
Consume verified webhooks, deduplicate by `x-agentbank-delivery-id`, and use
[Get payment](./reference/partner/get-payment) for recovery. Render `timeline`
as observed history grouped by `hop_index`; use `next_action` for what the
customer should do now, not a prior timeline item or an inferred future event.
Close the order only when `terminal` is `true`. A completed payment with
`successful: true` is a successful finish. A terminal failure with
`funds_moved: true` needs support or recovery, not automatic recreation.
# Rail readiness
Source: https://docs.useagentbank.com/partner-api/rail-readiness
Wait for provider KYC forwarding and confirm eligible fiat rails before payment creation.
KYC acceptance and provider readiness are separate states. AgentBank accepts a
complete KYC version first, then delivers it to the eligible providers and
reconciles their result asynchronously.
## Readiness response
[Get end user](./reference/partner/get-end-user) returns `rail_readiness`
entries with `fiat_currency`, `state`, `reason_code`, and `expires_at`.
Use each currency's state to decide whether to offer the payment:
| Rail state | Meaning | Merchant action |
| ------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
| `pending` | Provider evaluation is incomplete | Wait and poll or process the webhook |
| `available` | This end user can be used on the fiat rail | Estimate or create a compatible payment |
| `unavailable` | Provider cannot currently use the end user for that rail | Show the non-sensitive reason code and choose another rail/user |
| `suspended` | Use is temporarily blocked | Stop payment attempts and resolve the operational issue |
| `expired` | KYC or readiness needs renewal | Submit a new KYC version before using that rail |
The end-user `status` summarizes the set of rails. A user can be
`partially_available` when some rails are available and others are still
pending or unavailable. Do not infer eligibility from KYC status alone; check
the actual source or destination fiat currency required by the payment.
## Notifications
Subscribe to `end_user.kyc.accepted` and
`end_user.rail_readiness.updated`. Readiness can change more than once as each
provider or rail reaches a result. Treat the webhook data as a state
notification and fetch the end-user record when you need the complete current
list.
## Recommended UI behavior
1. Show KYC as submitted after a successful create or update.
2. Keep a payment option unavailable while its currency is `pending`.
3. Enable only the rails marked `available`.
4. On `unavailable`, `suspended`, or `expired`, display a safe next step without
exposing provider credentials or raw KYC details.
# List currencies
Source: https://docs.useagentbank.com/partner-api/reference/discovery/currencies
Read the active crypto and fiat asset catalog.
```text theme={null}
GET /api/currencies
```
**Authentication:** none. This public catalog is suitable for personal and
partner clients.
## Request
This endpoint has no query parameters or request body.
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/api/currencies"
```
## Response
```json theme={null}
{
"crypto": [
{
"asset_id": "asset_...",
"ticker": "USDC",
"chain": "worldchain",
"name": "USD Coin",
"address": "0x...",
"decimals": 6,
"status": "active",
"created_at": "1787000000000",
"logo_url": null,
"price_usd": "1",
"price_updated_at": "1787000000000"
}
],
"fiat": [
{
"symbol": "VND",
"name": "Vietnamese dong",
"description": null,
"decimals": 0,
"status": "active",
"created_at": "1787000000000"
}
]
}
```
Only `active` assets are returned. This is a catalog, not a live-corridor or
end-user-readiness check. Next call [List fiat payment capabilities](./fiat-payment-capabilities)
and then estimate the concrete payment.
# List fiat payment capabilities
Source: https://docs.useagentbank.com/partner-api/reference/discovery/fiat-payment-capabilities
Discover live on-ramp and off-ramp routes, plus final fiat recipient instruments for off-ramps.
```text theme={null}
GET /api/payment-capabilities
```
**Authentication:** none. This public API is shared by personal and partner
clients.
## Request
This endpoint has no parameters or request body.
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/api/payment-capabilities"
```
## Response
```json theme={null}
{
"capabilities": [
{
"fiat_currency": "VND",
"routes": [
{
"direction": "off_ramp",
"supported_payment_instruments": ["bank_transfer", "qr"],
"recipient_requirements": [
{
"payment_instrument": "bank_transfer",
"country": "VN",
"required_fields": ["country", "bank_name", "account_number", "holder_name"]
},
{
"payment_instrument": "qr",
"country": "VN",
"required_fields": ["qr_content"]
}
]
},
{
"direction": "on_ramp"
}
]
}
]
}
```
| Field | Meaning |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `fiat_currency` | The ISO-4217 fiat rail/currency. It is the currency-level country rail used by payment creation. |
| `direction` | `on_ramp` means the fiat-to-crypto corridor is live; `off_ramp` means crypto-to-fiat. |
| `supported_payment_instruments` | Present only for `off_ramp`; any of `qr`, `bank_transfer`, or `mobile_money` available for the final fiat recipient. |
| `recipient_requirements` | Present only for `off_ramp`; country, instrument, and required fields for the final fiat recipient. |
The response is derived from unexpired quote-book snapshots and can change. It
does not expose providers, rates, liquidity, an individual end user's readiness,
or a reservation. `recipient_requirements` can be empty for legacy live quotes.
Use [Get payment instrument schemas](./payment-instrument-schemas) to build
fields and estimate/create to make the final decision. An on-ramp intentionally
has no recipient fields here: its final recipient is a crypto address, not a
saved fiat recipient.
# Get payment instrument schemas
Source: https://docs.useagentbank.com/partner-api/reference/discovery/payment-instrument-schemas
Read the uniform recipient form schema for QR, direct bank transfer, and mobile money.
```text theme={null}
GET /api/payment-instruments/schema
```
**Authentication:** none. This public contract is shared by personal and
partner clients and is independent of fiat country.
## Request
This endpoint has no parameters or request body.
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/api/payment-instruments/schema"
```
## Response
```json theme={null}
{
"schema_version": 1,
"payment_instruments": [
{
"payment_instrument": "qr",
"fields": [
{"name":"qr_content","value_type":"string","required":true,"description":"Raw EMV or provider QR payload."},
{"name":"country","value_type":"string","required":false,"description":"Optional ISO alpha-2 recipient-country constraint."}
]
},
{
"payment_instrument": "bank_transfer",
"fields": [
{"name":"country","value_type":"string","required":true},
{"name":"bank_name","value_type":"string","required":true},
{"name":"account_number","value_type":"string","required":true},
{"name":"holder_name","value_type":"string","required":true},
{"name":"bank_code","value_type":"string","required":false}
]
},
{
"payment_instrument": "mobile_money",
"fields": [
{"name":"country","value_type":"string","required":true},
{"name":"mobile_money_network_code","value_type":"string","required":true},
{"name":"mobile_money_destination","value_type":"string","required":true}
]
}
]
}
```
Use this response to build a common recipient form. Then use
[List fiat payment capabilities](./fiat-payment-capabilities) to determine
which instrument/country combinations are live, and use
[List supported bank names](./supported-bank-names) when direct bank transfer
is selected. A QR `country` is optional here but can become required by the
selected live route's `recipient_requirements`.
# List supported bank names
Source: https://docs.useagentbank.com/partner-api/reference/discovery/supported-bank-names
Read the Core-curated direct bank-transfer name directory for a fiat rail.
```text theme={null}
GET /api/rails/:rail/supported-bank-names
```
**Authentication:** none. This directory is usable by personal and partner
clients for direct bank-transfer recipient forms.
## Path parameters
| Parameter | Required | Description |
| --------- | -------- | --------------------------------------- |
| `rail` | Yes | Uppercase fiat rail, for example `NGN`. |
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/api/rails/NGN/supported-bank-names"
```
## Response
```json theme={null}
{
"rail": "NGN",
"supported_bank_names": [
"GTBank Plc",
"StanbicIBTC Bank",
"PalmPay Limited"
]
}
```
Send the canonical string returned here as `bank_name`. This is a
Core-curated direct-bank directory, not a provider's complete bank list and
not a substitute for [Verify bank recipient](../partner/verify-bank-recipient).
# Cancel payment
Source: https://docs.useagentbank.com/partner-api/reference/partner/cancel-payment
Request cancellation of a merchant-owned payment before funding or where the current state permits it.
```text theme={null}
POST /v1/partner/payments/:paymentId/cancel
```
**Authentication:** signed Partner API request.
## Path parameters
| Parameter | Required | Description |
| ----------- | -------- | --------------------------------- |
| `paymentId` | Yes | Merchant-owned payment to cancel. |
## Request body
```json theme={null}
{"reason":"customer_changed_mind"}
```
`reason` is optional and has a 500-character maximum.
## Response
```json theme={null}
{
"payment_id": "pay_...",
"status": "cancelled",
"terminal": true,
"successful": false,
"funds_moved": false,
"next_action": {"type":"none","instruction":"No action is required.","poll_after_seconds":null},
"payment_instruction": null
}
```
Cancellation depends on the current settlement state. Do not tell an end user
that cancellation succeeded until the returned or subsequently read payment is
terminal with `status: "cancelled"`.
# Create end user
Source: https://docs.useagentbank.com/partner-api/reference/partner/create-end-user
Create a merchant-scoped end user from a complete KYC record and inline artifacts.
```text theme={null}
POST /v1/partner/end-users
```
**Authentication:** signed Partner API request. See [Authentication](../../authentication).
## Request body
`kyc` must be a complete `partner_end_user_kyc_v1` record. AgentBank generates
`end_user_id`; do not send one.
```json theme={null}
{
"kyc": {
"schema_version": "partner_end_user_kyc_v1",
"attestation": {
"collected_at": "2026-08-19T08:00:00Z",
"verified_at": "2026-08-19T08:02:00Z"
},
"person": {
"first_name": "Example",
"last_name": "Person",
"date_of_birth": "1990-01-02",
"gender": "female",
"nationality": "VN",
"country_of_residence": "VN",
"occupation": "employed"
},
"contact": {"email":"example@example.test","phone_e164":"+84912345678"},
"residential_address": {"line1":"1 Example Street"},
"identity_document": {
"type":"national_id",
"number":"TEST-DOCUMENT-ONLY",
"issuing_country":"VN",
"issued_on":"2021-01-01",
"expires_on":"2031-01-01"
},
"artifacts": {
"document_front":{"content_type":"image/jpeg","sha256":"","data_base64":""},
"document_back_not_applicable":true,
"selfie_with_document":{"content_type":"image/jpeg","sha256":"","data_base64":""},
"kyc_report_pdf":{"content_type":"application/pdf","sha256":"","data_base64":""}
}
}
}
```
See [End-user KYC](../../end-user-kyc) for the complete field and artifact
contract. Artifact hashes are lowercase SHA-256 hex of the decoded bytes.
## Response
```json theme={null}
{
"end_user_id": "peu_6fa6b3ee9bfe43db8700b04e8c91cc0b",
"status": "provider_processing",
"kyc_version": "1",
"kyc_summary": {
"schema_version": "partner_end_user_kyc_v1",
"nationality": "VN",
"country_of_residence": "VN",
"identity_document_type": "national_id"
},
"rail_readiness": [],
"updated_at": "1787000000000"
}
```
Persist `end_user_id`, then poll [Get end user](./get-end-user). Raw KYC,
document numbers, and artifact bytes are never returned.
# Create payment
Source: https://docs.useagentbank.com/partner-api/reference/partner/create-payment
Create one semantic on-ramp, off-ramp, or fiat-to-fiat payment.
```text theme={null}
POST /v1/partner/payments
```
**Authentication:** signed Partner API request.
## Request body
```json theme={null}
{
"request_id": "checkout-1042",
"end_user_id": "peu_6fa6b3ee9bfe43db8700b04e8c91cc0b",
"merchant_payment_reference": "invoice-1042",
"source": {
"asset": {"type":"crypto","ticker":"USDC","chain":"worldchain"},
"amount": "6"
},
"destination": {"asset":{"type":"fiat","symbol":"BRL"}},
"amount_mode": "exact_source",
"routing_preference": "balanced",
"recipient_fields": {
"payment_instrument": "qr",
"qr_content": "provider-approved-qr-content"
}
}
```
| Field | Required | Description |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `request_id` | Yes | Merchant correlation ID, maximum 128 characters. |
| `end_user_id` | Yes | AgentBank-issued end-user ID owned by the authenticated merchant. |
| `merchant_payment_reference` | Yes | Durable idempotency key, maximum 160 characters. |
| `source` / `destination` | Yes | Requested assets plus source amount for `exact_source`, or destination amount for `exact_destination`. |
| `amount_mode` | Yes | `exact_source` or `exact_destination`. |
| `routing_preference` | No | Defaults to `balanced`. |
| `recipient_fields` | Yes | Final payout recipient only. For fiat-to-fiat, never supply an internal bridge recipient. |
For a QR payout, send the QR payload and omit `rail`; Core derives the country
and fiat route from the QR. You may include `recipient_fields.country` only as
an ISO alpha-2 constraint, and it must match the detected country. For a direct
bank-transfer payout, include `country`, bank details, and holder name; Core
again derives the internal rail. Reuse the canonical `recipient_fields` from a
recipient preview when one was performed.
## Response
```json theme={null}
{
"payment_id": "pay_...",
"merchant_payment_reference": "invoice-1042",
"end_user_id": "peu_...",
"status": "funding_required",
"terminal": false,
"successful": false,
"routing": {"intermediate_asset":null,"hop_count":1},
"payment_instruction": {
"instruction_id": "payment:pay_...:hop:0",
"type": "crypto_deposit",
"amount": "6",
"asset": "USDC",
"pay_to": {"chain":"worldchain","address":"0x..."},
"expires_at": "2026-08-19T09:00:00.000Z"
},
"next_action": {"type":"fund","instruction":"Follow the server-generated funding instruction before it expires.","poll_after_seconds":null},
"hops": [{"index":0,"type":"off_ramp","status":"in_progress","instruction_available":true,"funds_moved":false}],
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:00:00.000Z"
}
```
The server-generated `payment_instruction` is authoritative. Preserve its
amount, asset, account/address, chain, memo, reference, calldata, and expiry.
Retry an uncertain create with the identical body and payment reference.
# Estimate payment
Source: https://docs.useagentbank.com/partner-api/reference/partner/estimate-payment
Get a non-binding, end-user-readiness-filtered quote for one payment direction.
```text theme={null}
POST /v1/partner/payments/estimate
```
**Authentication:** signed Partner API request.
## Request body
`direction` is `on_ramp` or `off_ramp`; direct `on_chain_swap` estimates are not
available on this endpoint. Send exactly one of `amount_in` or `amount_out`.
```json theme={null}
{
"end_user_id": "peu_6fa6b3ee9bfe43db8700b04e8c91cc0b",
"direction": "off_ramp",
"token_in": {"type":"crypto","ticker":"USDC","chain":"worldchain"},
"token_out": {"type":"fiat","symbol":"BRL"},
"amount_in": "6",
"preferred_rails": ["BRL"]
}
```
Optional fields are `expected_amount_in`, `expected_amount_out`,
`required_badges`, `required_reputation`, `deadline`, and `description`.
## Response
```json theme={null}
{
"intent_id": "int_...",
"best": {
"base_ccy": {"type":"crypto","ticker":"USDC","chain":"worldchain"},
"quote_ccy": {"type":"fiat","symbol":"BRL"},
"payment_method": "BRL",
"client_quote_id": "quote_...",
"rate": "5.12",
"fee_pct": "0.5",
"flat_fee": "0",
"fee_ccy": "USDC",
"min_amount": "1",
"max_amount": "1000",
"expiration": 1787000060000,
"supported_payment_instruments": ["qr", "bank_transfer"]
},
"all_quotes": []
}
```
An estimate does not reserve a route or authorize movement of funds. Call it
near checkout, then create the semantic payment once the user commits.
# Get end user
Source: https://docs.useagentbank.com/partner-api/reference/partner/get-end-user
Read redacted KYC state and current fiat-rail readiness for a merchant end user.
```text theme={null}
GET /v1/partner/end-users/:endUserId
```
**Authentication:** signed Partner API request, including an empty-body hash.
## Path parameters
| Parameter | Required | Description |
| ----------- | -------- | -------------------------------- |
| `endUserId` | Yes | AgentBank-generated end-user ID. |
```text theme={null}
GET /v1/partner/end-users/peu_6fa6b3ee9bfe43db8700b04e8c91cc0b
```
## Response
```json theme={null}
{
"end_user_id": "peu_6fa6b3ee9bfe43db8700b04e8c91cc0b",
"status": "partially_available",
"kyc_version": "2",
"kyc_summary": {"schema_version":"partner_end_user_kyc_v1","nationality":"VN"},
"rail_readiness": [
{"fiat_currency":"VND","state":"available","reason_code":null,"expires_at":null},
{"fiat_currency":"BRL","state":"pending","reason_code":null,"expires_at":null}
],
"updated_at": "1787000000000"
}
```
Create or estimate a payment only when its required fiat rail is `available`.
See [Rail readiness](../../rail-readiness) for every state.
# Get payment
Source: https://docs.useagentbank.com/partner-api/reference/partner/get-payment
Read the current aggregate, instruction, hops, and observed timeline for one B2B payment.
```text theme={null}
GET /v1/partner/payments/:paymentId
```
**Authentication:** signed Partner API request.
## Path parameters
| Parameter | Required | Description |
| ----------- | -------- | ------------------------------------ |
| `paymentId` | Yes | Merchant-owned `pay_...` payment ID. |
## Response
```json theme={null}
{
"payment_id": "pay_...",
"merchant_payment_reference": "invoice-1042",
"end_user_id": "peu_...",
"status": "in_progress",
"terminal": false,
"successful": false,
"funds_moved": true,
"payment_instruction": null,
"next_action": {"type":"wait","instruction":"Payment is being processed.","poll_after_seconds":10},
"hops": [{"index":0,"type":"off_ramp","status":"in_progress","instruction_available":false,"funds_moved":true}],
"timeline": [
{
"step_id": "step_...",
"settlement_id": "set_...",
"hop_index": 0,
"event": "crypto_received",
"step_code": "crypto_received",
"canonical": true,
"occurred_at": "2026-08-19T08:02:00.000Z",
"tx_hash": "0x...",
"detail": "6 USDC received by payment provider. Transaction 0x..."
}
],
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:02:00.000Z"
}
```
`timeline` is observed history only. Group it by `hop_index`; do not invent a
future provider event. Use `next_action` to decide whether the caller must
fund, wait, or take no further action. See [Funding and tracking](../../funding-and-tracking).
# List payments
Source: https://docs.useagentbank.com/partner-api/reference/partner/list-payments
List B2B payments owned by the signed merchant.
```text theme={null}
GET /v1/partner/payments
```
**Authentication:** signed Partner API request, including the query string in
the canonical path.
## Query parameters
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------------------------------------------------- |
| `status` | No | Comma-separated raw payment statuses. Cannot be combined with `state`. |
| `state` | No | One of `all`, `active`, `completed`, `pending`, or `failed`. |
| `created_after` | No | ISO-8601 timestamp lower bound. |
| `limit` | No | Page size from 1 to 100; default 50. |
| `offset` | No | Zero-based page offset; default 0. |
```text theme={null}
GET /v1/partner/payments?state=active&limit=20&offset=0
```
## Response
```json theme={null}
{
"total": 1,
"payments": [
{
"payment_id": "pay_...",
"merchant_payment_reference": "invoice-1042",
"status": "funding_required",
"terminal": false,
"successful": false,
"source": {"asset":{"type":"crypto","ticker":"USDC","chain":"worldchain"},"amount":"6"},
"destination": {"asset":{"type":"fiat","symbol":"BRL"}},
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:00:00.000Z"
}
]
}
```
The list contains only payments owned by the authenticating merchant and omits
the timeline. Read a specific payment for funding instructions and history.
# Parse QR recipient
Source: https://docs.useagentbank.com/partner-api/reference/partner/parse-qr-recipient
Detect a fiat QR's country and resolve its canonical recipient details without storing it.
```text theme={null}
POST /v1/partner/recipients/parse-qr
```
**Authentication:** signed Partner API request.
## Request body
| Field | Required | Description |
| ------------ | -------- | ----------------------------------------------------------------------------------------- |
| `qr_content` | Yes | Raw EMV or provider QR payload, maximum 4096 characters. |
| `country` | No | ISO alpha-2 constraint, for example `AR`. It must match the country detected from the QR. |
```json theme={null}
{
"qr_content": "00020101021143540016com.mercadolibre...630456C8"
}
```
Do not send `rail` or `end_user_id`. QR parsing is a merchant-scoped preview,
not a user KYC or payment-readiness check.
## Response
```json theme={null}
{
"country": "AR",
"payment_instrument": "qr",
"recipient_fields": {
"country": "AR",
"qr_content": "00020101021143540016com.mercadolibre...630456C8",
"payment_instrument": "qr",
"account_number": "23316888984",
"holder_name": "Example Recipient"
},
"derived_fields": [
{"name":"account_number","source":"provider_lookup"},
{"name":"holder_name","source":"qr_payload"}
],
"verification": "not_supported"
}
```
## Country detection and routing
AgentBank detects the country and validates the complete QR payload. If
`country` is supplied and differs from the detected country, the request fails
with `400 RECIPIENT_COUNTRY_MISMATCH`. A QR with no detectable supported country
also fails instead of guessing a route.
The resolved fields vary by country and provider. `verification` describes
whether an account-holder check was available; it is not itself a payment
status. This endpoint does not create an address-book record, reserve a route,
or verify the merchant end user's readiness. Send the returned
`recipient_fields` unchanged to [Create payment](./create-payment) after a
successful preview.
# Update end-user KYC
Source: https://docs.useagentbank.com/partner-api/reference/partner/update-end-user-kyc
Apply a versioned partial KYC update to a merchant end user.
```text theme={null}
PUT /v1/partner/end-users/:endUserId/kyc
```
**Authentication:** signed Partner API request.
## Path parameters
| Parameter | Required | Description |
| ----------- | -------- | -------------------------------------------------------------- |
| `endUserId` | Yes | AgentBank-generated `peu_...` ID owned by the signed merchant. |
## Request body
`base_kyc_version` must be the version from the latest end-user read. `kyc` is
a partial patch: omitted fields remain unchanged, while `null` and unknown
fields are rejected.
```json theme={null}
{
"base_kyc_version": "1",
"kyc": {
"contact": {"phone_e164":"+84999999999"}
}
}
```
## Response
```json theme={null}
{
"end_user_id": "peu_6fa6b3ee9bfe43db8700b04e8c91cc0b",
"status": "provider_processing",
"kyc_version": "2",
"kyc_summary": {"schema_version":"partner_end_user_kyc_v1","nationality":"VN"},
"rail_readiness": [{"fiat_currency":"VND","state":"pending","reason_code":null,"expires_at":null}],
"updated_at": "1787000000000"
}
```
On a KYC version conflict, read the end user, merge only allowed changes, and
send a new patch. Do not retry a stale version unchanged.
# Verify bank recipient
Source: https://docs.useagentbank.com/partner-api/reference/partner/verify-bank-recipient
Validate and resolve a final direct bank-transfer recipient without storing it.
```text theme={null}
POST /v1/partner/recipients/verify-bank
```
**Authentication:** signed Partner API request.
## Request body
| Field | Required | Description |
| ---------------- | -------- | --------------------------------------------------------------------------- |
| `end_user_id` | Yes | Merchant end user used for provider-aware validation. |
| `country` | Yes | Recipient ISO alpha-2 country. Core derives the internal fiat rail from it. |
| `bank_name` | Yes | Canonical bank name, preferably from the public bank directory. |
| `account_number` | Yes | Payout account number. |
| `holder_name` | Yes | Recipient display/legal holder name. |
| `bank_code` | No | A provider/bank code already known by the caller. |
```json theme={null}
{
"end_user_id": "peu_6fa6b3ee9bfe43db8700b04e8c91cc0b",
"country": "PH",
"bank_name": "UnionBank (InstaPay)",
"account_number": "23316888984",
"holder_name": "Example Person"
}
```
## Response
```json theme={null}
{
"country": "PH",
"payment_instrument": "bank_transfer",
"recipient_fields": {
"country": "PH",
"bank_name": "UnionBank (InstaPay)",
"account_number": "23316888984",
"holder_name": "Example Person"
},
"derived_fields": [
{"name":"bank_name","source":"input"},
{"name":"account_number","source":"input"},
{"name":"holder_name","source":"provider_verified"}
],
"verification": "verified"
}
```
Do not send `rail`; country is the external routing input for a direct bank
recipient. Provider validation can return `verified`, `unverified`, or
`not_supported`. The value describes account-holder validation availability and
outcome, not a payment status. Always use the returned canonical fields; the
call has no persistence side effect.
# Create webhook
Source: https://docs.useagentbank.com/partner-api/reference/portal/create-webhook
Register a merchant webhook endpoint and receive its one-time HMAC signing secret.
```text theme={null}
POST /v1/merchant/webhooks
```
**Authentication:** `Authorization: Bearer `.
## Request body
```json theme={null}
{
"url": "https://merchant.example/webhooks/agentbank"
}
```
`url` must be an absolute URL and can be up to 2,000 characters. It must be
publicly reachable over HTTPS in production.
## Response
```json theme={null}
{
"endpoint_id": "mwe_...",
"url": "https://merchant.example/webhooks/agentbank",
"status": "active",
"signing_scheme": "hmac_sha256_v1",
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:00:00.000Z",
"disabled_at": null,
"signing_secret": "shown-once-only"
}
```
Persist `signing_secret` before continuing. It is returned only by this
endpoint and cannot be recovered, read, or changed later. See
[Portal and webhooks](../../portal-and-webhooks) for delivery verification.
# Delete webhook
Source: https://docs.useagentbank.com/partner-api/reference/portal/delete-webhook
Soft-disable a merchant webhook endpoint.
```text theme={null}
DELETE /v1/merchant/webhooks/:endpointId
```
**Authentication:** `Authorization: Bearer `.
## Path parameters
| Parameter | Required | Description |
| ------------ | -------- | ------------------------------------- |
| `endpointId` | Yes | Merchant-owned `mwe_...` endpoint ID. |
## Request
This request has no body.
```bash theme={null}
curl -sS -X DELETE "$AGENTBANK_BASE_URL/v1/merchant/webhooks/mwe_..." \
-H "Authorization: Bearer $PORTAL_JWT"
```
## Response
```json theme={null}
{
"endpoint_id": "mwe_...",
"url": "https://merchant.example/webhooks/agentbank",
"status": "disabled",
"signing_scheme": "hmac_sha256_v1",
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:20:00.000Z",
"disabled_at": "2026-08-19T08:20:00.000Z"
}
```
Deletion stops future deliveries but does not revoke prior deliveries or alter
their signatures. A disabled endpoint cannot be re-enabled; create a new one.
# Get current portal user
Source: https://docs.useagentbank.com/partner-api/reference/portal/get-current-user
Read the merchant identity associated with a portal JWT.
```text theme={null}
GET /v1/merchant/me
```
**Authentication:** `Authorization: Bearer `.
## Request
This endpoint has no parameters or request body.
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/v1/merchant/me" \
-H "Authorization: Bearer $PORTAL_JWT"
```
## Response
```json theme={null}
{
"merchant_partner_id": "mp_...",
"merchant_portal_user_id": "mpu_...",
"username": "example_merchant"
}
```
Use this to confirm that a cached portal token belongs to the intended merchant
before showing read-only history or webhook configuration.
# Portal get payment
Source: https://docs.useagentbank.com/partner-api/reference/portal/get-payment
Read a merchant-owned payment aggregate and its observed timeline through the portal API.
```text theme={null}
GET /v1/merchant/payments/:paymentId
```
**Authentication:** `Authorization: Bearer `.
## Path parameters
| Parameter | Required | Description |
| ----------- | -------- | ------------------------------------ |
| `paymentId` | Yes | Merchant-owned `pay_...` payment ID. |
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/v1/merchant/payments/pay_..." \
-H "Authorization: Bearer $PORTAL_JWT"
```
## Response
```json theme={null}
{
"payment_id": "pay_...",
"merchant_payment_reference": "invoice-1042",
"status": "in_progress",
"terminal": false,
"successful": false,
"next_action": {"type":"wait","instruction":"Payment is being processed.","poll_after_seconds":10},
"timeline": [
{
"step_id": "step_...",
"hop_index": 0,
"event": "crypto_received",
"detail": "6 USDC received by payment provider. Transaction 0x...",
"tx_hash": "0x..."
}
]
}
```
The response matches the signed [Get payment](../partner/get-payment) resource
but is read-only and authenticated with the portal JWT.
# Get webhook
Source: https://docs.useagentbank.com/partner-api/reference/portal/get-webhook
Read metadata for one merchant-owned webhook endpoint.
```text theme={null}
GET /v1/merchant/webhooks/:endpointId
```
**Authentication:** `Authorization: Bearer `.
## Path parameters
| Parameter | Required | Description |
| ------------ | -------- | ------------------------------------- |
| `endpointId` | Yes | Merchant-owned `mwe_...` endpoint ID. |
## Response
```json theme={null}
{
"endpoint_id": "mwe_...",
"url": "https://merchant.example/webhooks/agentbank",
"status": "active",
"signing_scheme": "hmac_sha256_v1",
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:00:00.000Z",
"disabled_at": null
}
```
The endpoint's signing secret is intentionally absent. If it was lost, create
a replacement endpoint and change the receiver to its new secret.
# Portal list payments
Source: https://docs.useagentbank.com/partner-api/reference/portal/list-payments
List payment history owned by the merchant authenticated through the portal JWT.
```text theme={null}
GET /v1/merchant/payments
```
**Authentication:** `Authorization: Bearer `.
## Query parameters
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------------------------------------------------- |
| `status` | No | Comma-separated raw payment statuses. Cannot be combined with `state`. |
| `state` | No | `all`, `active`, `completed`, `pending`, or `failed`. |
| `created_after` | No | ISO-8601 timestamp lower bound. |
| `limit` | No | 1-100, default 50. |
| `offset` | No | Zero-based page offset, default 0. |
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/v1/merchant/payments?state=completed&limit=20" \
-H "Authorization: Bearer $PORTAL_JWT"
```
## Response
```json theme={null}
{
"total": 1,
"payments": [
{
"payment_id": "pay_...",
"merchant_payment_reference": "invoice-1042",
"status": "completed",
"terminal": true,
"successful": true,
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:03:00.000Z"
}
]
}
```
The portal returns only the authenticated merchant's B2B payments. The list
does not contain the timeline; read a payment for detail.
# List webhooks
Source: https://docs.useagentbank.com/partner-api/reference/portal/list-webhooks
List active and disabled webhook endpoints for the portal merchant.
```text theme={null}
GET /v1/merchant/webhooks
```
**Authentication:** `Authorization: Bearer `.
## Request
This endpoint has no path, query, or body parameters.
```bash theme={null}
curl -sS "$AGENTBANK_BASE_URL/v1/merchant/webhooks" \
-H "Authorization: Bearer $PORTAL_JWT"
```
## Response
```json theme={null}
[
{
"endpoint_id": "mwe_...",
"url": "https://merchant.example/webhooks/agentbank",
"status": "active",
"signing_scheme": "hmac_sha256_v1",
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:00:00.000Z",
"disabled_at": null
}
]
```
The one-time `signing_secret` is never included in a list or read response.
# Portal login
Source: https://docs.useagentbank.com/partner-api/reference/portal/login
Exchange provisioned portal credentials for a merchant portal JWT.
```text theme={null}
POST /v1/merchant/auth/login
```
**Authentication:** none. This endpoint is rate limited; use only from a
trusted merchant backend or portal server, never an untrusted client.
## Request body
```json theme={null}
{
"username": "example_merchant",
"password": "replace-with-provisioned-secret"
}
```
`username` is 3-64 characters. `password` is 12-256 characters.
## Response
```json theme={null}
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_at": "2026-08-19T09:00:00.000Z",
"merchant_partner_id": "mp_..."
}
```
Send `Authorization: Bearer ` to all other portal endpoints.
Portal credentials and JWTs never authorize KYC or payment creation; use the
signed Partner API for those operations.
# Update webhook
Source: https://docs.useagentbank.com/partner-api/reference/portal/update-webhook
Replace the URL of one active merchant webhook endpoint.
```text theme={null}
PATCH /v1/merchant/webhooks/:endpointId
```
**Authentication:** `Authorization: Bearer `.
## Path parameters
| Parameter | Required | Description |
| ------------ | -------- | -------------------------------------------- |
| `endpointId` | Yes | Active merchant-owned `mwe_...` endpoint ID. |
## Request body
```json theme={null}
{
"url": "https://merchant.example/webhooks/agentbank-v2"
}
```
## Response
```json theme={null}
{
"endpoint_id": "mwe_...",
"url": "https://merchant.example/webhooks/agentbank-v2",
"status": "active",
"signing_scheme": "hmac_sha256_v1",
"created_at": "2026-08-19T08:00:00.000Z",
"updated_at": "2026-08-19T08:10:00.000Z",
"disabled_at": null
}
```
Only the URL changes. The signing secret and endpoint identity remain the same.
A disabled endpoint cannot be updated.
# Cancel or correct a payment
Source: https://docs.useagentbank.com/payments/cancel-or-correct
Ask to stop an unfunded payment or fix recipient details when allowed.
## Cancel a payment
> “Can I cancel the payment I just started?”
Tell your assistant which payment you mean. It checks the current status and
whether cancellation is available, then asks you to confirm before cancelling.
Ask it to check the result afterward; requesting cancellation is not proof
that the payment stopped.
Cancellation is available only before funds move and in supported payment
states. It cannot reverse a funded transfer. If you already sent money, tell
your assistant before doing anything else and use
[payment recovery](/payments/recover-failures).
## Correct a recipient
> “The recipient details on this payment are wrong. What can I do?”
Your assistant can correct an existing payment only when AgentBank has paused
it specifically to request recipient correction. Provide the requested details,
review the corrected recipient, and confirm the change. Your assistant then
checks what the payment needs next.
Changing a [saved recipient](/money-out/manage-recipients) does not change a
payment already in progress. If correction is not offered, ask whether the
payment can be cancelled or needs support.
Do not start or fund a replacement while the original payment is unresolved.
Check that it has ended and whether any funds moved before deciding to try again.
Builders: see the [cancellation](/reference/tools/cancel-payment) and
[recipient correction](/reference/tools/correct-payment-recipient) references.
# Payment cards in chat
Source: https://docs.useagentbank.com/payments/hosted-payment-cards
Review, approve, fund, and track payments in ChatGPT or Claude.
When you [connect from ChatGPT or Claude](/getting-started/hosted-oauth),
AgentBank can display payment cards inside your conversation. Cards keep
approval, funding, and progress in the appropriate AgentBank or Privy experience.
## Quote preview
Check both amounts, all fees and their currencies, the conversion route, the
recipient, and the expiry before confirming. This preview does not reserve a
rate or move money.
## Approval
If World ID approval is required, complete it in the approval card. If you
cannot find the card, ask: “Show the approval for my payment again.” Never
paste World ID proofs or raw approval QR data into chat.
## Payment plans
For a [payment plan](/payments/payment-plans), review every payment and the
totals together. When World ID is required, one approval covers the submitted
plan. Each payment still has its own funding instruction and result.
## Funding instruction
Ask: “Show me how to fund this payment.” If you closed or missed the card,
your assistant can reopen the current instructions for the existing payment.
Follow the displayed bank, QR, mobile-money, or other supported instructions.
For an eligible crypto deposit, you can fund manually or explicitly choose an
active, compatible [spending grant](/autonomy/spending-grants).
You can also ask for a shareable payment link when one is available. Links are
not available for every payment. For someone else to pay, see
[Collect from another payer](/money-in/collect-from-a-payer).
## Swap signing
For a crypto swap, follow the signing page opened by your assistant and sign
through Privy yourself. Spending grants cannot be used for swaps.
## Progress
After you send funds, ask: “Show the progress of my payment.” Your assistant
can display a progress card and check AgentBank's recorded status. Treat the
payment as complete only when AgentBank reports completion, not merely when
you finish a bank transfer or wallet action.
Opening a card or link, or completing World ID approval, does not fund the
payment. Your assistant must wait for your separate, explicit choice before
using a spending grant for the current payment instruction.
Builders: see the [hosted connection reference](/reference/mcp-overview).
# Overview
Source: https://docs.useagentbank.com/payments/overview
Track a payment, manage several together, or get help when something goes wrong.
You can return to an existing payment after leaving the conversation or
closing a payment card. Tell your assistant which payment you mean and ask
for its status or next step.
Understand where your payment is and whether you need to act.
Approve, fund, and follow progress in ChatGPT or Claude.
Review several payments together and track each one's result.
Stop an unfunded payment when allowed or fix a requested recipient detail.
Resume an interrupted payment without sending money twice.
A bank transfer confirmation or wallet receipt alone is not proof of delivery.
Your assistant should check whether AgentBank reports the payment completed.
# Payment plans
Source: https://docs.useagentbank.com/payments/payment-plans
Review several payments together, then fund and track each separately.
Use a payment plan when you want to review and confirm several payments
together, such as paying several recipients.
> “Help me pay these three recipients as one plan. I have their bank details and the amounts each should receive.”
## What to provide
For each payment, give the recipient, destination currency, and either the
amount you want to spend or the amount they should receive. Include the asset
or currency you want to pay from and the network when relevant. Your assistant
checks availability and asks for missing details for each item.
Check every recipient, source and destination amount, fee and fee currency,
conversion route, expiry, and warning. Review the totals as well as each
individual payment. Make any changes before confirming.
Explicitly confirm the complete reviewed list. Your assistant submits the
plan, which can no longer be edited. Complete one combined World ID
approval if it is required.
Follow each payment's own funding instructions. The plan does not combine
balances, recipients, or funding into one transfer. Crypto funding still
requires the appropriate explicit authorization or your wallet signature.
Ask your assistant which payments completed and which still need action.
Each settles independently; one completed payment does not mean the whole
plan succeeded.
## If you change your mind
Ask your assistant whether the plan can be cancelled before funds move.
Cancellation cannot reverse payments that have already been funded. If some
payments are pending or have failed, check each one's status before creating
replacements.
Builders: see the [plan reference](/reference/tools/create-payment-plan).
# Recover a payment
Source: https://docs.useagentbank.com/payments/recover-failures
Find the next safe step for an interrupted, expired, or failed payment.
> “My payment seems stuck. I already sent the money—can you check what happened?”
Tell your assistant which payment you mean, what you were doing when the
problem happened, and whether you sent money or signed a wallet action. A
payment reference or approximate date, amount, and recipient can help it find
the right record.
Your assistant checks AgentBank's current status, the reason for the
problem, whether funds moved, and the next available action. It should
not start a replacement just because a screen closed or a response was lost.
Reopen the existing approval or funding instructions if they are still
valid. If a bank transfer or wallet action is unresolved, keep checking
it instead of sending again.
If AgentBank requests corrected recipient details, review and confirm
them. If you want to stop, ask whether cancellation is still possible and
confirm before proceeding.
If funds moved and your assistant cannot resolve the problem, contact
support with the payment reference, current status, failure details, and
whether you already paid. Never send wallet secrets or login credentials.
## Expired or timed-out payments
An expiry or timeout does not by itself prove that no money moved. Have your
assistant check before trying again. If no funds moved and a new payment is
needed, review a fresh quote and confirm its terms. If funds did move, continue
tracking or contact support instead of funding a replacement.
Do not repeat a bank transfer, wallet action, or payment simply because its
result is unclear. A second attempt could send money twice.
See [Contact support](/support/contact) and
[Cancel or correct a payment](/payments/cancel-or-correct).
Builders: see the [retry safety reference](/reference/idempotency).
# Payment status and tracking
Source: https://docs.useagentbank.com/payments/track-payments
Understand your payment's progress, what needs action, and when it is complete.
> “Has my payment to Linh arrived?”
Tell your assistant the payment reference if you have it, or describe the
recipient, amount, and approximate date. It can find payments available to
your connection. If several match, choose the correct one before proceeding.
## From quote to completion
1. **Quote:** you review the amounts, fees, recipient, route, and expiry. No payment has been created and no money has moved.
2. **Confirmation and approval:** you confirm the payment and complete World ID approval if required.
3. **Funding:** you follow the bank instructions or separately authorize the wallet action. Opening an instruction or approving with World ID does not send money.
4. **Processing:** AgentBank detects the funds and follows the payment through to its destination.
5. **Result:** AgentBank reports completion or explains why the payment ended without completing.
## What the status means for you
| What your assistant reports | What to do |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| Approval needed | Complete the current approval request. |
| Ready to fund | Open the current instructions and follow them once. |
| Detecting funds or processing | Keep tracking the existing payment; do not send again. |
| Under review | Follow any requested action or wait for the review result. |
| Recipient correction needed | Review and confirm the requested correction. |
| Completed | AgentBank reports that the full payment completed. |
| Cancelled, expired, timed out, or failed | Check the reason and whether funds moved before attempting a new payment. |
Your assistant should explain the current status and any action you need to
take. In ChatGPT or Claude, ask it to reopen a missing funding card before
payment, or show progress after funds move.
A bank transfer confirmation, crypto transaction receipt, or one completed
conversion is not proof that the full payment finished. Rely on AgentBank's
reported payment result. Never create a replacement just because approval or
funding detection is still pending.
Need help? See [Recover a payment](/payments/recover-failures) or
[Cancel or correct a payment](/payments/cancel-or-correct).
Builders: see the [status reference](/reference/statuses).
# x402 outbound payments
Source: https://docs.useagentbank.com/payments/x402-payments
Pay an external x402 resource through a supported live fiat on-ramp.
Use the dedicated x402 tools only when a requested external URL returns an
x402 payment challenge.
Call `estimate_x402_outbound_payment` with the exact URL, HTTP method,
optional request body, and requested fiat funding asset. The tool validates
the challenge and creates a durable outbound intent without moving funds.
Show the external USDC requirement, exact fiat amount, fees, pay-to
address, and `confirm_before`. Obtain explicit confirmation.
Call `confirm_x402_outbound_payment` with the returned intent ID and
`confirmed_by_user=true`. Follow the server-generated on-ramp instruction.
Poll `get_x402_outbound_payment` until terminal. Use
`list_x402_outbound_payments` to recover an existing intent when its ID is
unknown.
Outbound x402 currently supports live fiat on-ramps only. Do not construct an
x402 header, EIP-3009 authorization, transaction, or signature locally. A USDC
transaction hash alone does not prove that the external resource accepted the
payment; require the durable intent to report `completed` and
`successful=true`.
# Local approval policy
Source: https://docs.useagentbank.com/reference/approval-policy
Read and update a local agent's World ID approval threshold.
These tools are available on the local stdio MCP connection:
| Tool | Purpose | Confirmation |
| -------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| `get_payment_approval_policy` | Read this agent's World ID approval threshold. | Read-only. |
| `update_payment_approval_policy` | Change this agent's threshold. | Obtain explicit confirmation of the proposed change first. |
Use the tool schema exposed by the connected server for exact input fields.
The threshold contributes to the current approval policy; it does not replace
payment review, account readiness, or a separate funding authorization.
Follow the payment's returned approval status.
These tools are not part of the Remote MCP surface. Users can also manage
their threshold on [the AgentBank platform](https://app.useagentbank.com).
See [Set your approval threshold](/autonomy/configure-thresholds) for the
user-facing instructions.
# MCP configuration
Source: https://docs.useagentbank.com/reference/configuration
Configure AgentBank endpoints, transport, credentials, and local profiles.
| Variable | Meaning | Default |
| -------------------------------- | ----------------------------------------------------------- | ------------------------------------ |
| `PROTOCOL_BASE_URL` | Protocol Core API base URL | `https://protocol.useagentbank.com/` |
| `APP_BASE_URL` | First-party AgentBank app base URL | `https://app.useagentbank.com/` |
| `MCP_TRANSPORT` | MCP transport mode | stdio unless set to `http` |
| `AGENTBANK_MCP_PROFILE` | Stable local identity and credential profile | `default` |
| `AGENTBANK_MCP_CREDENTIAL_STORE` | Local vault backend (`auto`, `keychain`, or managed `file`) | platform default |
| `AGENTBANK_MCP_KEY_STORE_SECRET` | Managed-file vault passphrase supplied outside the model | none |
| `AGENTBANK_MCP_KEY_STORE_FILE` | Optional managed encrypted-vault path | platform configuration directory |
Trailing slashes are removed before use. Explicit environment values override
defaults.
Normal production setup requires no endpoint overrides. Browser authorization
and the local credential vault manage the installation session. Keep
`AGENTBANK_MCP_PROFILE` stable across restarts and use a different profile for
each local human or agent identity.
On Linux, the default vault is protected by the OS-user boundary and the host's
disk and backup controls. Copying the complete vault directory also copies its
local key. Managed hosts that require a separately supplied passphrase can use
the `file` store and inject `AGENTBANK_MCP_KEY_STORE_SECRET` outside the model
and repository.
Hosted OAuth connections do not use a local MCP credential profile.
Never commit credentials, vault secrets, or encrypted vault files to the
documentation repository or paste them into chat or support messages.
# Errors and reason codes
Source: https://docs.useagentbank.com/reference/errors
Recover safely from common AgentBank MCP errors without duplicate payments.
| Error or reason | Meaning | Safe response |
| ------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| `MISSING_CREDENTIAL` | No connected-agent credential is available | Begin browser authorization once |
| `UNAUTHENTICATED` | The active local session may have expired | Call `relogin` once, then retry the original operation |
| `CREDENTIAL_PROFILE_MISMATCH` | The selected local profile does not match the stored installation | Restore the correct `AGENTBANK_MCP_PROFILE`; do not re-onboard |
| `CREDENTIAL_STORE_UNAVAILABLE` | The local credential vault cannot be opened | Follow the returned OS or managed-vault remediation |
| `IDEMPOTENCY_CONFLICT` | A request ID was reused with a different payload | Use the original payload or create a new ID for the changed action |
| `QUOTE_EXPIRED` | The reviewed quote is no longer live | Estimate again, show the refreshed terms, and reconfirm |
| `PRICE_MISMATCH` | Live validation no longer matches the reviewed economic terms | Estimate again and reconfirm; never substitute silently |
| `need_review` | The payment cannot advance automatically | Read the reason and current payment state |
| `rail_not_ready` | KYC or market readiness is incomplete | No payment was created and no funds moved; wait and retry safely |
Also handle expired quotes, insufficient balance, unsupported assets, missing
recipient fields, ambiguous transaction submission, recipient correction, and
terminal failure after funds moved.
Do not present this page as an exhaustive backend error catalog. Tool responses
and `get_payment` remain authoritative.
# Idempotency and request IDs
Source: https://docs.useagentbank.com/reference/idempotency
Retry AgentBank mutations without creating duplicate logical actions.
Every exposed mutation except onboarding uses a client-generated request ID
where its schema includes one.
* Reuse an ID only for the same logical request and identical payload.
* Use a new ID when any material field changes.
* The same ID and body replay the original result.
* The same ID with a different body returns `IDEMPOTENCY_CONFLICT`.
Payment-instruction execution binds idempotency to the owner, connected agent,
payment, instruction, pinned wallet, instruction hash, execution plan, and
stable request ID. An ambiguous retry reuses the same signed body and key.
Unresolved aged submissions enter manual review and must not be rebroadcast
with a replacement key.
# Limitations
Source: https://docs.useagentbank.com/reference/limitations
Understand the explicit non-capabilities of the current AgentBank MCP surface.
* No automatic Core planner selects a settlement asset for two-step routes.
* Estimates are ephemeral and have no ID. Creation live-validates their quote
references and never silently replaces them.
* Expired or rejected payment authorization cannot be refreshed in place.
* Partial two-step failure has no dedicated automated recovery action.
* QR images are decoded, but text-only screenshot OCR is not implemented.
* Recipient updates create replacements and do not revoke the old record.
* No generic arbitrary EVM transaction tool is exposed.
* Partner identity and partner-query APIs are hidden.
* Legacy low-level settlement workflows are outside the production surface.
* A pending AgentKit verification session may need to be recreated after MCP
restart.
* Remote MCP can return a shareable action link with `get_payment_link` when
one is available for that payment. Do not assume every route or connection
offers one; use the returned bank or QR instructions when applicable.
* The agent can track whether a collection was paid, not who paid it.
* Spending grants apply only to hosted crypto-deposit funding; they cannot
authorize fiat funding or swaps.
# MCP overview
Source: https://docs.useagentbank.com/reference/mcp-overview
Find AgentBank tool contracts, connection boundaries, and agent integration guidance.
AgentBank MCP exposes payment tools, account state, and workflow guidance.
The [AgentBank Pay skill](https://useagentbank.com/SKILL.md) supplies operating
instructions for agents. AgentBank Core enforces permissions, payment policy,
instructions, and final status.
## Connection surfaces
| | Local stdio | Remote HTTP |
| -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| Setup | [Local MCP package](/getting-started/connect-your-agent) | [ChatGPT or Claude OAuth connection](/getting-started/hosted-oauth) |
| Identity | Per-installation credential and stable local profile | Signed-in user's OAuth connection |
| Onboarding | Local enrollment tools | Client-managed browser authorization |
| Crypto funding | Execute the current payment instruction after confirmation | Owner action or a separately chosen compatible spending grant |
| Disconnect | Confirm and call `revoke_agent` | Revoke in AgentBank connection settings |
Available tools depend on the connection and granted scopes. Inspect the live
tool list and `check_my_scopes`; do not rely on a fixed tool count or attempt
local onboarding on a remote connection.
The remote AgentBank MCP endpoint is `https://mcp.useagentbank.com`. The
MCP server listed in this documentation site's `/.well-known/mcp.json` is
documentation search only; payments go through the AgentBank MCP.
## Find the right reference
Inputs, authorization, confirmation, and retry behavior.
Local profiles, endpoints, and credential storage.
Setup, payment, routing, and recovery guidance.
Resolve connection and execution errors.
MCP prompts and resources are guidance interfaces, separate from callable
tools. See [Resources and prompt](/reference/resources).
# MCP resources and prompt
Source: https://docs.useagentbank.com/reference/resources
Read AgentBank runtime routing and journey instructions through standard MCP discovery.
AgentBank exposes:
* prompt: `agentbank_routing_guide`
* fixed resource: `agentbank://guides/routing`
* resource template: `agentbank://instructions/{journey}`
* journeys: `setup`, `pay`, `track`, `recover`, `manage_recipients`, and
`manage_wallets`
Clients access these through standard MCP prompt and resource discovery,
including resource listing, template listing, and resource reading. They are
not callable tools.
During the naming migration, a deployed server may still return a legacy
`humanfx` identifier. Treat it as a compatibility alias and follow the same
runtime guidance.
# Scopes
Source: https://docs.useagentbank.com/reference/scopes
Understand the normal permissions requested by an AgentBank connected agent.
The normal local-onboarding scope request is:
```text theme={null}
quote:read
intent:create
route:create
settlement:prepare
settlement:initiate
recipient:read
recipient:write
agent_wallet:use
agent:revoke
```
Quote discovery uses `quote:read`; payment creation and tracking use settlement
scopes; recipient tools use read or write scopes; wallet execution uses
`agent_wallet:use`; revocation uses `agent:revoke`.
Use `check_my_scopes` as a diagnostic, but note that its displayed map may still
contain legacy compatibility entries even when backend enforcement is correct.
Hosted OAuth grants connection-specific scopes and exposes a different tool
surface. Use `check_my_scopes` and the live tool list rather than applying the
local onboarding scope list to a hosted connection.
# Payment statuses
Source: https://docs.useagentbank.com/reference/statuses
Interpret AgentBank durable payment states and choose the next safe action.
| Status | Meaning | Next action |
| ------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `approval_required` | World ID payment authorization is pending | Open the returned first-party action and keep the same payment |
| `approval_ready` | Authorization is satisfied | Call `continue_payment` |
| `funding_required` | A fiat or wallet funding instruction is ready | Follow the current instruction |
| `funding_detecting` | AgentBank is detecting or verifying funding | Poll `get_payment` |
| `processing` | Funds moved and the route is processing | Poll at the returned cadence; do not fund again |
| `need_review` | A readiness or manual review condition blocks progress | Read the reason and do not duplicate the payment |
| `recipient_correction_required` | Settlement is paused for corrected recipient details | Confirm and call `correct_payment_recipient` |
| `completed` | The aggregate payment completed | Report completion |
| `cancelled` | The durable payment was cancelled | Stop |
| `expired` | The current payment or funding window expired | Read `failure`, confirm that funds did not move, and estimate again if the user wants to retry |
| `funding_timeout` | Funding was not detected before the payment's funding window closed | Read `funds_moved` and the returned recovery guidance before creating anything new |
| `failed` | The payment reached a terminal failure | Show failure details and whether funds moved |
`get_payment` is authoritative. A transaction hash, completed hop, or hosted
card state does not replace the aggregate payment status.
# approve_token
Source: https://docs.useagentbank.com/reference/tools/approve-token
Submit an exact ERC-20 approval only when the requested allowance is insufficient.
**Authentication:** `agent_wallet:use`\
**Surface:** Local stdio only
**Mutates state:** Maybe; on-chain when needed\
**Idempotency:** Stable `request_id`\
**Confirmation:** `confirmed_by_user=true`
```json theme={null}
{
"request_id": "stable transaction retry ID",
"confirmed_by_user": true,
"chain_id": 480,
"token_address": "0x...",
"spender": "0x...",
"amount_atomic": "100000000"
}
```
If allowance is already sufficient, returns `already_sufficient` and sends
nothing. Otherwise it submits exact `approve(spender, amount_atomic)` through
the bound Privy wallet.
Never infer or request an unlimited amount. Use the exact amount required by a
current supported action.
# begin_agent_onboarding
Source: https://docs.useagentbank.com/reference/tools/begin-agent-onboarding
Start or resume browser authorization for a local AgentBank connected agent.
**Authentication:** None\
**Mutates state:** Yes\
**Request ID:** Not required
```json theme={null}
{ "agent_name": "optional display name" }
```
The MCP reuses an unexpired local pending device flow when possible. Otherwise
it generates the installation key locally, starts Privy device authorization,
creates a pending AgentBank enrollment, and stores private material outside
model content.
Returns an `enrollment_id`, `agent_installation_id`, status,
`authorization_url`, requested scopes, expiry, and instructions.
Show the single returned URL and do not start a second flow while it remains
pending. Continue with `wait_for_agent_onboarding`.
# browse_quote_book
Source: https://docs.useagentbank.com/reference/tools/browse-quote-book
Browse anonymous quote groups and amount bands without creating an intent.
**Authentication:** `quote:read`\
**Mutates state:** No
```json theme={null}
{
"base_ccy": { "type": "crypto", "ticker": "USDC", "chain": "worldchain" },
"quote_ccy": { "type": "fiat", "symbol": "VND" },
"direction": "off_ramp",
"rail": "optional payment-method filter",
"include_expired": false
}
```
Returns anonymous, unranked groups and bands. The raw `rate` excludes fees;
always evaluate `fee_pct`, `flat_fee`, and `fee_ccy` together. This tool does
not select an amount band or create an intent.
# cancel_payment
Source: https://docs.useagentbank.com/reference/tools/cancel-payment
Cancel a durable payment while cancellation remains valid.
**Authentication:** `settlement:prepare`\
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`\
**Confirmation:** Obtain explicit user confirmation before calling
```json theme={null}
{
"request_id": "stable retry ID",
"payment_id": "pay_...",
"reason": "optional"
}
```
Call only after reading `get_payment`. Core requests cancellation of opened
non-terminal settlements, expires unopened route agreements, and returns the
unified view.
If funds moved, do not report cancellation from intent alone. Trust the
returned payment and failure state. A pending World ID challenge may remain
visible until expiry but cannot resume a cancelled payment.
# cancel_payment_plan
Source: https://docs.useagentbank.com/reference/tools/cancel-payment-plan
Cancel a plan before any child payment has moved funds.
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`
```json theme={null}
{
"payment_plan_id": "plan_...",
"request_id": "stable plan-cancel ID",
"reason": "User abandoned the batch"
}
```
Cancels unstarted child payments and releases unopened route locks. It never
interrupts a child payment after funds move.
# check_my_scopes
Source: https://docs.useagentbank.com/reference/tools/check-my-scopes
Compare granted scopes with the MCP server's configured tool-scope map.
**Authentication:** Valid connected-agent credential\
**Mutates state:** No
```json theme={null}
{}
```
Returns granted scopes, wildcard state, and the configured
`required_scope`/`usable` view.
The backend is authoritative. The displayed map may include legacy hidden tools
or omit high-level payment tools, so do not treat it as the production
`tools/list` inventory.
# check_verification_status
Source: https://docs.useagentbank.com/reference/tools/check-verification-status
Read the account owner's KYC state, badges, and fiat-market readiness.
**Authentication:** Valid connected-agent credential\
**Mutates state:** No
```json theme={null}
{}
```
KYC states include `none`, `pending`, `in_review`, `verified`, `rejected`,
`expired`, and `abandoned`.
Market readiness is keyed by country and uses `APPROVED`, `PENDING`,
`NOT_STARTED`, or `REJECTED`. Current market mappings include ARS, BRL, IDR,
NGN, PEN, PHP, THB, and VND.
This readiness view does not prove that a live quote exists. Use
`list_quote_book_pairs` and `browse_quote_book` for live availability.
# confirm_x402_outbound_payment
Source: https://docs.useagentbank.com/reference/tools/confirm-x402-outbound-payment
Confirm a reviewed x402 intent and open its exact fiat funding route.
**Mutates state:** Yes\
**Confirmation:** `confirmed_by_user=true`
```json theme={null}
{
"x402_outbound_intent_id": "x402_...",
"pay_with": {
"asset": { "type": "fiat", "symbol": "USD" },
"payment_instrument": "bank_transfer"
},
"confirmed_by_user": true,
"client_quote_id": "quote_..."
}
```
Call only after showing the external USDC requirement, exact fiat amount,
fees, pay-to address, and `confirm_before`. Follow the returned on-ramp
instruction exactly. Do not construct a payment signature locally.
# continue_payment
Source: https://docs.useagentbank.com/reference/tools/continue-payment
Open approved settlement steps and return the payment's current instruction.
**Authentication:** `settlement:initiate`\
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`
```json theme={null}
{ "request_id": "stable retry ID", "payment_id": "pay_..." }
```
Before authorization is ready, returns the payment view without opening
settlements. After authorization, Core opens unopened steps in descending
order so a downstream off-ramp can produce its deposit destination before the
upstream step funds it.
The result may include `instruction_id`, type, amount, asset, destination,
expiry, a first-party presentation URL, and swap execution metadata.
On hosted OAuth, this tool displays a dedicated funding card. Do not duplicate
its action links unless requested or unavailable. Fiat, QR, mobile-money, and
payment-link instructions are completed through that card. For a
`crypto_deposit`, stop and wait for a new user choice between manual card
funding and a compatible spending grant. For a hosted swap, the owner signs
through the returned `transaction_signing_url`.
In a linked two-step payment, never fund the downstream deposit separately.
The upstream route is already bound to it.
# correct_payment_recipient
Source: https://docs.useagentbank.com/reference/tools/correct-payment-recipient
Correct recipient fields for a payment paused on an invalid recipient.
**Authentication:** `settlement:prepare`\
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`\
**Confirmation:** `confirmed_by_user=true`
```json theme={null}
{
"request_id": "stable retry ID",
"payment_id": "pay_...",
"recipient_fields": {},
"confirmed_by_user": true
}
```
Valid only when the payment has a settlement in
`recipient_correction_required` with an `invalid_recipient` step. Core
resubmits the canonical fields and returns the updated aggregate.
It is rejected when the payment is merely in `need_review`.
# create_payment
Source: https://docs.useagentbank.com/reference/tools/create-payment
Persist a payment, independently validate its route, and create its authorization state.
**Authentication:** `settlement:prepare`\
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`\
**Confirmation:** `confirmed_by_user=true` under the active authorization policy
```json theme={null}
{
"request_id": "client-generated stable ID",
"confirmed_by_user": true,
"source": { "asset": {}, "amount": "..." },
"destination": { "asset": {}, "amount": "...", "recipient_id": "..." },
"amount_mode": "exact_source",
"routing_preference": "balanced",
"intermediate_asset": {},
"hops": [
{
"hop_index": 0,
"intent_id": "...",
"direction": "on_ramp",
"source": "quote_accept",
"client_quote_id": "..."
},
{
"hop_index": 1,
"intent_id": "...",
"direction": "off_ramp",
"source": "quote_accept",
"client_quote_id": "..."
}
]
}
```
One or two hops are allowed. Directions are `on_ramp`, `off_ramp`, and
`on_chain_swap`; sources are `quote_accept` and `auto_selected`. Two hops
require top-level `intermediate_asset`. Hops contain route data only; MCP binds
the top-level destination recipient and the internal two-hop reference.
For a plan-bound payment, also provide `plan_id` and a unique `plan_position`.
Its confirmation occurs when the complete plan is submitted, so it does not
use standalone `confirmed_by_user`.
Core independently validates quote references, amount continuity, readiness,
and the route. If the fiat rail is not ready, it returns `need_review` with
`payment_created=false` and `reason=rail_not_ready`; no payment or authorization
was created.
A successful result is the durable payment view. Use the exact hops from an
unexpired estimate while its inputs are unchanged. On `QUOTE_EXPIRED` or
`PRICE_MISMATCH`, estimate again and reconfirm the refreshed terms.
When status is `approval_required`, hosted OAuth calls
`show_payment_approval`; local clients show the expiring first-party approval
URL. When status is `approval_ready`, continue the same payment.
# create_payment_plan
Source: https://docs.useagentbank.com/reference/tools/create-payment-plan
Create a draft that will contain several independently settled payments.
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`
```json theme={null}
{
"request_id": "stable plan-create ID",
"description": "Monthly supplier payouts"
}
```
The draft moves no funds and opens no settlements. Add items with
`create_payment` using the returned `plan_id`, a unique `plan_position`, and a
unique request ID for each payment.
# create_recipient
Source: https://docs.useagentbank.com/reference/tools/create-recipient
Parse, validate, and register a fiat or crypto recipient from supported input forms.
**Authentication:** `recipient:write`\
**Mutates state:** Yes when validation succeeds\
**Idempotency:** Stable `request_id`
```json theme={null}
{
"request_id": "stable retry ID",
"rail": "VND",
"type": "fiat",
"payment_instrument": "bank_transfer",
"fields": {},
"bank_info": {
"bank_name": "optional",
"account_number": "19030936530017",
"holder_name": "optional",
"country": "VN",
"key": "optional",
"address": "optional"
},
"pasted_text": "optional labeled bank details or raw QR content",
"qr_content": "optional raw QR payload",
"image": {
"path": "absolute local path for stdio only",
"data_base64": "base64 or data URI for remote transport",
"mime_type": "image/png"
},
"is_default_wallet": false
}
```
`request_id`, `rail`, `type`, and at least one input source are required. Fiat
recipients also require exactly one `payment_instrument` selected from the
estimate's `recipient_requirements`: `qr`, `bank_transfer`, or `mobile_money`.
Use exactly one of `image.path` or `image.data_base64`. Images are limited to 10
MB decoded data and must contain machine-readable QR content; OCR is not
provided.
On hosted OAuth, call `get_supported_bank_names` before a bank-transfer
recipient when the tool is available. If it is unavailable, submit the user's
bank name and let Core validate or canonicalize it.
The tool either returns `information_required` without writing, or registers
canonical fields and returns the recipient plus a reusable payment destination.
# do_kyc
Source: https://docs.useagentbank.com/reference/tools/do-kyc
Start hosted KYC when the account owner is not already verified.
**Authentication:** Valid connected-agent credential\
**Mutates state:** May start a KYC session
```json theme={null}
{}
```
If the owner already has the KYC badge, returns `already_verified` without
starting a session. Otherwise it creates a Didit session and returns `kyc_url`
with human-only completion instructions.
The agent shows the URL but cannot complete KYC or grant consent for the user.
Recheck with `check_verification_status` afterward.
# estimate_payment
Source: https://docs.useagentbank.com/reference/tools/estimate-payment
Preview a complete direct, swap, or explicit two-step payment route.
**Authentication:** `quote:read`, `intent:create`\
**Mutates state:** May create quote intents; does not create a payment
```json theme={null}
{
"source": {
"asset": { "type": "fiat", "symbol": "PHP" },
"amount": "23729.64"
},
"destination": {
"asset": { "type": "fiat", "symbol": "VND" },
"amount": "10000000",
"country": "VN"
},
"amount_mode": "exact_destination",
"routing_preference": "lowest_total_cost",
"route": {
"intermediate_asset": {
"type": "crypto",
"ticker": "USDC",
"chain": "worldchain"
}
}
}
```
Supports direct on/off-ramp, same-chain swap, fiat-to-fiat, and
token-to-fiat routes. Estimates are recipient-free. A two-step estimate
requires an explicit intermediate asset selected from live pairs.
The result is ephemeral: it has no estimate ID, creates no payment or
executable calldata, and may contain expiring quote references. For fiat
destinations, `recipient_requirements` defines the supported instruments and
required recipient fields. Collect the final recipient only after the user
chooses one of those instruments.
Reuse an `estimate_ready` result while its economic inputs are unchanged and
`expires_at` has not passed. Pass its `hops` unchanged to `create_payment` or a
plan-bound payment. Re-estimate only after expiry, a material input change,
`QUOTE_EXPIRED`, or `PRICE_MISMATCH`, and reconfirm changed terms.
# estimate_x402_outbound_payment
Source: https://docs.useagentbank.com/reference/tools/estimate-x402-outbound-payment
Validate an external x402 challenge and create a durable outbound intent.
**Mutates state:** Creates a durable outbound intent; moves no funds
```json theme={null}
{
"x402_url": "https://example.com/paid-resource",
"request": { "method": "GET" },
"pay_with": {
"asset": { "type": "fiat", "symbol": "USD" },
"payment_instrument": "bank_transfer"
}
}
```
The tool fetches the exact external request, validates a supported Worldchain
USDC requirement, and returns an intent ID, fiat funding amount, fees, pay-to
address, and confirmation deadline. Current public execution supports live
fiat on-ramp funding only.
# execute_payment_instruction
Source: https://docs.useagentbank.com/reference/tools/execute-payment-instruction
Execute only the current Core-owned payment instruction through the pinned wallet.
**Authentication:** `settlement:initiate`, `agent_wallet:use`\
**Surface:** Local stdio only
**Mutates state:** Yes; on-chain\
**Idempotency:** Stable execution `request_id`\
**Confirmation:** `confirmed_by_user=true` under the active authorization policy
```json theme={null}
{
"request_id": "stable execution retry ID",
"payment_id": "pay_...",
"instruction_id": "ins_...",
"confirmed_by_user": true
}
```
The caller cannot choose the wallet, chain, token, spender, amount, target,
value, calldata, or execution order. Core validates the current instruction,
pins the payment route and wallet, and derives an exact transfer or swap plan.
For swaps, Core checks allowance, submits an exact approval only when needed,
rechecks allowance, and sends the final hash for verification. Retry ambiguous
submissions with the same request ID.
The result omits wallet IDs, RPC bodies, Privy authorization material, and
Privy transaction IDs. Continue tracking with `get_payment`.
Hosted OAuth uses manual card action or `fund_payment_with_grant` for an
explicitly authorized crypto deposit. Hosted swaps use the first-party signing
URL.
# fund_payment_with_grant
Source: https://docs.useagentbank.com/reference/tools/fund-payment-with-grant
Fund the current hosted crypto-deposit instruction with an active compatible grant.
**Surface:** Hosted OAuth\
**Mutates state:** Submits the current immutable payment instruction\
**Idempotency:** Stable `request_id`\
**Confirmation:** A new explicit funding choice for this instruction
```json theme={null}
{
"request_id": "stable funding ID",
"payment_id": "pay_...",
"instruction_id": "instruction_...",
"wallet_id": "wallet_...",
"confirmed_by_user": true
}
```
The caller cannot supply an amount, recipient, transaction, chain, or calldata.
Call only after the funding card was displayed and a later user response chose
automatic grant funding. Reuse the same request ID while execution remains
pending. Never use this tool for fiat instructions or swaps.
# get_account_status
Source: https://docs.useagentbank.com/reference/tools/get-account-status
Read combined installation, scope, verification, wallet, blocker, and next-action readiness.
**Authentication:** Valid connected-agent credential\
**Surface:** Local stdio only
**Mutates state:** No
```json theme={null}
{}
```
Returns installation state, scopes and mode, owner verification, public wallet
readiness, blockers, and next action.
`ready=true` is account-level readiness, not proof that every fiat market is
approved. Check `check_verification_status` for a fiat rail and use wallet tools
for wallet-funded journeys.
# get_installation_status
Source: https://docs.useagentbank.com/reference/tools/get-installation-status
Read safe enrollment and scope metadata for a known installation.
**Authentication:** None\
**Surface:** Local stdio only
**Mutates state:** No
```json theme={null}
{ "agent_installation_id": "agi_..." }
```
Returns safe enrollment and scope metadata. It does not return installation
keys, sessions, Privy tokens, or wallet secrets.
Use this for setup diagnostics when an installation ID is known. Use `whoami`
for the currently authenticated connected agent.
# get_instructions
Source: https://docs.useagentbank.com/reference/tools/get-instructions
Read current server guidance for an AgentBank journey.
**Authentication:** None\
**Mutates state:** No
```json theme={null}
{ "journey": "pay", "client_version": "optional" }
```
Valid journeys are `setup`, `pay`, `track`, `recover`,
`manage_recipients`, and `manage_wallets`.
Returns a version, required tools, ordered steps, human actions, safety rules,
retry rules, and terminal statuses. Follow newer runtime guidance when it does
not conflict with the AgentBank Pay skill's safety rules.
# get_payment
Source: https://docs.useagentbank.com/reference/tools/get-payment
Read the authoritative durable aggregate for one payment.
**Authentication:** `settlement:prepare`\
**Mutates state:** No
```json theme={null}
{ "payment_id": "pay_...", "include_debug": false }
```
`include_debug=true` requires `debug:read` or wildcard scope.
Returns status, terminal and success flags, summary, retryability, canonical
source, redacted destination, amount mode, routing, authorization, current
instruction, `funds_moved`, failure, next action, public step summaries, and
timestamps.
Public statuses are `approval_required`, `approval_ready`, `funding_required`,
`funding_detecting`, `processing`, `need_review`,
`recipient_correction_required`, `completed`, `cancelled`, `expired`,
`funding_timeout`, and `failed`.
This is the authoritative payment state. Internal orchestration identifiers and
sensitive recipient fields are omitted.
On hosted OAuth this read is card-free. Reopen a missed pre-funding card with
`get_payment_instruction`; after funds move, display `show_payment_progress`.
# get_payment_instruction
Source: https://docs.useagentbank.com/reference/tools/get-payment-instruction
Reopen a hosted funding card when the current instruction was missed.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{ "payment_id": "pay_..." }
```
Use only when the user asks to see the current instruction again or reports
that the card is unavailable. Do not use `get_payment` to reopen a card. After
displaying a crypto-deposit instruction, wait for a new user choice before
inspecting or using spending grants.
# get_recipient
Source: https://docs.useagentbank.com/reference/tools/get-recipient
Read one saved recipient by ID.
**Authentication:** `recipient:read`\
**Mutates state:** No
```json theme={null}
{ "recipient_id": "recipient_..." }
```
Returns the matching saved recipient. An unknown ID produces a not-found input
error. Use the canonical returned fields rather than reconstructing recipient
details from conversation history.
# get_spending_grant
Source: https://docs.useagentbank.com/reference/tools/get-spending-grant
Inspect one selected hosted spending grant without displaying its card.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{ "grant_id": "grant_..." }
```
Use only when the grant list lacks detail needed for a selected candidate. To
display a pending grant for activation, call `show_spending_grant` instead.
# get_supported_bank_names
Source: https://docs.useagentbank.com/reference/tools/get-supported-bank-names
Read canonical bank names for a hosted fiat rail when the directory is available.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{ "rail": "VND" }
```
Pass the destination currency rail from the quote, not an instrument or
provider name. Use a matching canonical value in a bank-transfer recipient.
If the lookup is unavailable or the directory is empty, pass the user's bank
name to `create_recipient` and let Core validate or canonicalize it. Do not
require QR solely because directory lookup is unavailable.
# get_supported_payment_capabilities
Source: https://docs.useagentbank.com/reference/tools/get-supported-payment-capabilities
Read a general product-capability summary without checking live route readiness.
**Mutates state:** No
```json theme={null}
{}
```
Returns a static Markdown summary of generally supported fiat funding and
payout currencies, settlement assets, and networks. It does not prove that a
route is live, in the requested amount band, or ready for the current user.
Use `list_quote_book_pairs` and `estimate_payment` for an executable request.
# get_token_allowance
Source: https://docs.useagentbank.com/reference/tools/get-token-allowance
Read an ERC-20 allowance for the bound wallet, token, and spender.
**Authentication:** `agent_wallet:use`\
**Surface:** Local stdio only
**Mutates state:** No
```json theme={null}
{
"chain_id": 480,
"token_address": "0x...",
"spender": "0x...",
"decimals": 6
}
```
Returns the owner wallet, token, spender, raw allowance, formatted allowance,
and resolved decimals. Prefer execution tools that derive these values from a
current payment instruction rather than asking the user to supply them.
# get_transaction_receipt
Source: https://docs.useagentbank.com/reference/tools/get-transaction-receipt
Resolve a sponsored send or read the on-chain receipt for a wallet transaction.
**Authentication:** Valid credential; reported as `agent_wallet:use`\
**Surface:** Local stdio only
**Mutates state:** No
```json theme={null}
{ "chain_id": 480, "tx_hash": "0x32-byte-hash" }
```
For a sponsored send without a chain hash:
```json theme={null}
{ "chain_id": 480, "request_id": "original wallet mutation request ID" }
```
With `request_id`, Core verifies that the transaction belongs to the bound
wallet and returns the final hash when available. Receipt results include
`pending`, `confirmed`, or `failed`, confirmation count, block, status,
from/to, gas, contract address, and logs.
A successful receipt is chain evidence only. `get_payment` is authoritative for
payment completion.
# get_verification_guidance
Source: https://docs.useagentbank.com/reference/tools/get-verification-guidance
Get first-party guidance for KYC and World ID requirements.
**Authentication:** Valid connected-agent credential\
**Mutates state:** No
```json theme={null}
{}
```
Returns KYC and World ID needs, a first-party AgentBank profile URL, and
guidance. The agent may start KYC but cannot complete KYC, grant user consent,
or perform World ID verification for the user.
# get_wallet_balances
Source: https://docs.useagentbank.com/reference/tools/get-wallet-balances
Read native and ERC-20 balances for the bound AgentBank wallet.
**Authentication:** `agent_wallet:use`\
**Surface:** Local stdio only
**Mutates state:** No
```json theme={null}
{
"chain_id": 480,
"tokens": [{ "address": "0x...", "symbol": "USDC", "decimals": 6 }]
}
```
Returns the wallet address plus native and token balances in raw and formatted
units. When `tokens` is omitted, it queries active AgentBank tokens for the
selected configured chain.
Use `list_currencies` to verify supported chains, token addresses, and decimals
instead of guessing them.
# get_x402_outbound_payment
Source: https://docs.useagentbank.com/reference/tools/get-x402-outbound-payment
Read the authoritative state of one outbound x402 intent.
**Mutates state:** No
```json theme={null}
{ "x402_outbound_intent_id": "x402_..." }
```
Poll the same intent through fiat funding and external submission. Treat only
`status=completed` with `successful=true` as proof that both funding and the
external x402 request succeeded.
# list_currencies
Source: https://docs.useagentbank.com/reference/tools/list-currencies
List active fiat and crypto metadata used by AgentBank routes.
**Authentication:** Public\
**Mutates state:** No
```json theme={null}
{}
```
Returns crypto asset IDs, tickers, chains, token addresses, decimals, status,
logos, and optional USD price metadata, plus fiat symbols, names, descriptions,
decimals, status, and creation time.
Use this tool whenever the agent needs to verify a ticker, fiat code, chain,
token contract, or decimals. Do not infer these values.
# list_payment_plans
Source: https://docs.useagentbank.com/reference/tools/list-payment-plans
List payment plans visible to the current connection.
**Mutates state:** No
```json theme={null}
{}
```
Returns plan summaries with aggregate approval and execution state. Use it to
resume an existing plan instead of creating a duplicate after interruption.
# list_payments
Source: https://docs.useagentbank.com/reference/tools/list-payments
List durable payments scoped to the current local installation or hosted OAuth connection.
**Authentication:** `settlement:prepare`\
**Mutates state:** No
```json theme={null}
{
"status": ["completed"],
"created_after": "2026-07-26T00:00:00Z",
"limit": 50,
"offset": 0
}
```
Returns durable Core records visible to the current local installation or
hosted OAuth connection. Results survive restarts. Pagination uses `offset` and
`limit`.
# list_quote_book_pairs
Source: https://docs.useagentbank.com/reference/tools/list-quote-book-pairs
List live direct on-ramp and off-ramp currency pairs without creating an intent.
**Authentication:** `quote:read`\
**Mutates state:** No
```json theme={null}
{ "direction": "optional on_ramp or off_ramp" }
```
Returns `{total, pairs[]}` with canonical `base_ccy`, `quote_ccy`, and
direction. Use it to discover direct corridors or join one on-ramp and one
off-ramp pair on the same crypto asset for an explicit two-step route.
# list_recipients
Source: https://docs.useagentbank.com/reference/tools/list-recipients
List active saved payout destinations for the current account.
**Authentication:** `recipient:read`\
**Mutates state:** No
```json theme={null}
{}
```
Returns recipient ID, rail, type, canonical fields, schema version,
holder-verification metadata, default-wallet flag, status, and registration
time.
`verified:false` means verified holder metadata has not been established. It
does not by itself make the recipient malformed or unusable; the live route
remains authoritative.
# list_spending_grants
Source: https://docs.useagentbank.com/reference/tools/list-spending-grants
List spending grants owned by the current hosted OAuth connection.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{}
```
Use the returned status and scope to select a grant compatible with the exact
crypto asset and chain. Do not inspect grants until the user has chosen
automatic funding for the current instruction, and do not fetch every
historical grant individually.
# list_wallets
Source: https://docs.useagentbank.com/reference/tools/list-wallets
List the public AgentBank wallet bound to the current connection.
**Authentication:** `agent_wallet:use`\
**Mutates state:** No
```json theme={null}
{}
```
Local stdio returns the wallet bound during browser onboarding. Hosted OAuth
returns the owner's shared Privy wallet for that connection. Both surfaces
expose public wallet identifiers and addresses only.
Use the returned wallet rather than asking the user to paste or infer an
address.
# list_x402_outbound_payments
Source: https://docs.useagentbank.com/reference/tools/list-x402-outbound-payments
Find earlier outbound x402 intents for recovery and tracking.
**Mutates state:** No
```json theme={null}
{
"status": "pending",
"x402_url": "https://example.com/paid-resource",
"limit": 20
}
```
Results are newest first. The URL filter is exact and may still match several
historical purchases. Compare the request, amount, status, and time before
choosing one. Resume the existing intent instead of creating a replacement.
# Tool overview
Source: https://docs.useagentbank.com/reference/tools/overview
Understand AgentBank MCP capabilities and the tools available on local and hosted connections.
The reference navigation groups tools by setup and identity, discovery,
payments, payment plans, x402, hosted OAuth, recipients, and wallet operations.
Available tools vary by MCP surface and granted scopes.
Choose the correct setup, revocation, and wallet-execution model.
Group multiple independent payments under one approval.
Pay an external x402 resource through a supported fiat on-ramp.
Use embedded approval, funding, progress, and spending-grant tools.
Use `check_my_scopes` and the live tool list to determine what the current
connection can call. Each linked tool page documents its surface, mutation
behavior, confirmation boundary, idempotency, and safe retry rules.
# relogin
Source: https://docs.useagentbank.com/reference/tools/relogin
Refresh an expired session for the active local AgentBank installation.
**Surface:** Local stdio only\
**Mutates state:** Refreshes the current installation session
```json theme={null}
{}
```
Call once after `UNAUTHENTICATED` or an expired-session response, then retry
the original operation. The tool signs a fresh Core challenge with the locally
stored installation key. It accepts and returns no credential, key, challenge,
or signature.
Do not start a new onboarding flow for a session that can be refreshed.
# request_spending_grant
Source: https://docs.useagentbank.com/reference/tools/request-spending-grant
Create a pending, bounded Privy spending grant for a hosted wallet.
**Surface:** Hosted OAuth\
**Mutates state:** Creates a pending grant\
**Idempotency:** Stable `request_id`\
**Confirmation:** `confirmed_by_user=true` after reviewing scope and limits
```json theme={null}
{
"request_id": "stable grant-request ID",
"asset_and_chain_scope": {},
"per_transaction_limit_atomic": "1000000",
"rolling_limit_atomic": "5000000",
"rolling_window_seconds": 86400,
"confirmed_by_user": true
}
```
The grant has no spending authority until the owner activates it through the
attached card. Show the raw activation URL only when requested or when the
card is unavailable.
# review_payment_plan
Source: https://docs.useagentbank.com/reference/tools/review-payment-plan
Review the authoritative ordered contents and totals of a draft payment plan.
**Mutates state:** No
```json theme={null}
{ "payment_plan_id": "plan_..." }
```
Returns ordered payment details, grouped totals, routes, fees, expiries,
approval state, and the next action. Verify every intended item and position,
then obtain one explicit confirmation for the complete plan. Review does not
refresh an expired quote or revise a locked route.
# revoke_agent
Source: https://docs.useagentbank.com/reference/tools/revoke-agent
Revoke the current connected agent and clear its local credentials.
**Authentication:** Valid credential with `agent:revoke`\
**Surface:** Local stdio only
**Mutates state:** Yes\
**Confirmation:** `confirm=true`
```json theme={null}
{ "confirm": true }
```
The connected agent can revoke only itself. Core invalidates the installation,
sessions, and bound wallet authorization. The MCP removes the local
installation key, session, active marker, Privy device state, and Privy tokens.
This disconnects the agent. Explain the impact and obtain explicit user
confirmation before calling.
Hosted OAuth connections are revoked from AgentBank connection settings.
# show_payment_approval
Source: https://docs.useagentbank.com/reference/tools/show-payment-approval
Display the hosted World ID approval card for a payment that requires approval.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{ "payment_id": "pay_..." }
```
Call immediately after `create_payment` returns `approval_required`. Do not
also repeat the approval link in chat unless the user asks or the card is
unavailable. Never expose a raw World ID request or proof.
# show_payment_progress
Source: https://docs.useagentbank.com/reference/tools/show-payment-progress
Display the hosted lifecycle card after payment funds have moved.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{ "payment_id": "pay_..." }
```
Call after `get_payment` confirms that funds moved. Do not show it while the
payment is awaiting funding; the funding instruction and progress views are
separate cards.
# show_spending_grant
Source: https://docs.useagentbank.com/reference/tools/show-spending-grant
Display the activation or status card for one selected spending grant.
**Surface:** Hosted OAuth\
**Mutates state:** No
```json theme={null}
{ "grant_id": "grant_..." }
```
Use for a pending grant the owner needs to activate or when the owner asks to
reopen its card. Do not call it merely to inspect a grant.
# submit_payment_plan
Source: https://docs.useagentbank.com/reference/tools/submit-payment-plan
Seal a reviewed plan and create its single World ID approval.
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`\
**Confirmation:** `confirmed_by_user=true` after reviewing the complete plan
```json theme={null}
{
"payment_plan_id": "plan_...",
"request_id": "stable plan-submit ID",
"confirmed_by_user": true
}
```
Submission permanently seals the plan and prepares one approval covering all
items when required. Do not request individual World ID approvals for child
payments. After approval, track and continue each payment independently.
# update_recipient
Source: https://docs.useagentbank.com/reference/tools/update-recipient
Register a confirmed replacement for an existing recipient.
**Authentication:** `recipient:write`\
**Mutates state:** Yes\
**Idempotency:** Stable `request_id`\
**Confirmation:** `confirmed_by_user=true`
```json theme={null}
{
"request_id": "stable retry ID",
"recipient_id": "recipient_...",
"fields": {},
"confirmed_by_user": true
}
```
Core has no in-place recipient update endpoint. This tool registers a
replacement and returns `replaced_recipient_id`; it does not automatically
revoke the old record.
# verify_agent_kit
Source: https://docs.useagentbank.com/reference/tools/verify-agent-kit
Start or refresh AgentKit verification for the single bound AgentBank wallet.
**Authentication:** `agent_wallet:use`\
**Surface:** Local stdio and Remote MCP
**Mutates state:** May start a verification session
```json theme={null}
{}
```
If verification is required, returns `verification_url`, expiry, and
`next_action.type=verify_in_world_app`. The user opens or scans the URL in
World App, then the agent calls this tool again until
`agentkit_verified=true`.
This is separate from KYC, the owner's World ID badge, and payment-specific
World ID authorization. The tool exposes no wallet secret.
# wait_for_agent_onboarding
Source: https://docs.useagentbank.com/reference/tools/wait-for-agent-onboarding
Poll browser authorization and finalize the connected agent and wallet binding.
**Authentication:** None\
**Mutates state:** Yes\
**Request ID:** Not required
```json theme={null}
{ "enrollment_id": "optional pending ID", "timeout_ms": 600000 }
```
`timeout_ms` defaults to ten minutes and is capped at fifteen minutes. The MCP
polls Privy and AgentBank, authenticates the selected Ethereum-compatible
wallet, signs the binding with the local installation key, finalizes
enrollment, and stores the connected-agent session locally.
Safe result fields include `privy_authorized`, `wallet_bound`, public wallet
details, and `authenticated`.
Reuse the same enrollment ID after a pending timeout. No credential, private
key, or signing key is returned.
# whoami
Source: https://docs.useagentbank.com/reference/tools/whoami
Identify the current connected agent, account owner, scopes, mode, and owner badges.
**Authentication:** Valid connected-agent credential\
**Mutates state:** No
```json theme={null}
{}
```
Returns `agent_installation_id`, `owner_subject_id`, granted scopes, mode,
actor type, and the linked account owner's live badges. The badges belong to
the owner, not the agent.
Call this first when beginning AgentBank work. On local stdio, if it returns
`MISSING_CREDENTIAL`, start browser authorization with
`begin_agent_onboarding`. Remote MCP uses the client's OAuth sign-in flow;
do not run local onboarding on a remote connection.
# MCP troubleshooting
Source: https://docs.useagentbank.com/reference/troubleshooting
Diagnose local enrollment, credential, and payment-execution failures.
For user-facing next steps, see [Troubleshooting](/support/troubleshooting).
These diagnostics are for agents and integration builders.
## Local connection and credentials
| Condition | Action |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Tools absent | Check Node.js, `npx`, and client configuration, then reload the client. OpenClaw can run `openclaw mcp doctor agentbank --probe`. |
| `MISSING_CREDENTIAL` | Begin local onboarding once and wait with the returned enrollment ID. |
| Enrollment pending or wait timeout | Resume the same enrollment ID while valid; do not create a second flow. |
| Expired local session | Call `relogin` once, then retry the original operation. |
| `CREDENTIAL_PROTECTOR_LOCKED`, `CREDENTIAL_STORE_CORRUPT`, or `CREDENTIAL_PROFILE_MISMATCH` | Preserve the installation and follow the returned OS, vault, or profile remediation. |
Use [Local authorization flow](/getting-started/authentication) for enrollment
sequencing. Remote MCP uses OAuth in the host client instead of these local
enrollment or session tools.
## Payment recovery
Read `get_payment` before taking recovery action. Preserve the current payment
and instruction while they remain valid.
* On `QUOTE_EXPIRED` or `PRICE_MISMATCH`, obtain a fresh estimate and reconfirm
the changed terms before creation.
* For `rail_not_ready` with `payment_created=false`, wait for approved readiness;
no payment was created. Reuse a request ID only for an identical payload.
* For missing recipient fields, collect only those requested and use a new
request ID when the payload changes.
* After ambiguous local execution, reuse the same execution request ID. Never
rebroadcast an unresolved submission with a replacement idempotency key.
* For a hosted swap, return to the first-party signing action and read payment
state. Do not substitute local wallet execution or a spending grant.
* Reopen a missing funding card with `get_payment_instruction`. Once funds
moved, use `show_payment_progress` for the progress card.
Expired or rejected approval cannot be refreshed in place. Before replacing
an expired payment, read `funds_moved` and the failure guidance. If funds moved,
continue tracking or escalate instead of funding a new payment.
See [Errors](/reference/errors), [Idempotency](/reference/idempotency), and
[Payment statuses](/reference/statuses) for the detailed contracts.
# Connect ChatGPT
Source: https://docs.useagentbank.com/remote-mcp/chatgpt
Add AgentBank to ChatGPT and sign in to your account.
This setup uses ChatGPT's custom MCP connection. Developer mode availability
depends on your account and workspace policy.
Open **Settings → Security and login** in ChatGPT and turn on
**Developer mode**.
Open [ChatGPT Plugins](https://chatgpt.com/plugins), select the plus button,
and enter **AgentBank** as the name. Add a short description such as
“Collect payments, exchange currencies, and send money with AgentBank.”
Under **Connection**, enter:
```text theme={null}
https://mcp.useagentbank.com
```
Create the connection and review the available tools.
Complete AgentBank's browser sign-in when prompted. Choose your account
and review the requested permissions.
Start a new chat and add AgentBank from the tools menu. Ask:
```text theme={null}
Check my AgentBank account and wallet. Tell me if any setup is still needed.
```
Confirm that the connected account is yours.
Continue with [Your first payment](/getting-started/first-payment) or
[Example prompts](/ai-guides/conversation-patterns).
If developer mode is unavailable, check your account or workspace policy.
Use exactly `https://mcp.useagentbank.com` without adding `/mcp`, and ensure AgentBank is
enabled in the current conversation.
If the available tools have changed, open the connection in ChatGPT Plugins,
select **Refresh**, and start a new conversation. For a missing payment card,
ask the assistant to reopen it.
See OpenAI's [connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt)
for the current interface and access requirements.
# Connect Claude
Source: https://docs.useagentbank.com/remote-mcp/claude
Add AgentBank as a Claude remote connector and sign in to your account.
Use a custom remote connector in Claude or Claude Desktop. No local MCP
package is required for this setup.
Claude supports remote connectors on Free, Pro, Max, Team, and Enterprise.
Free accounts are limited to one custom connector. The individual steps below
follow Claude's Pro and Max guide; see the
[current connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
for your account's available setup.
Open **Customize → Connectors**, select **+**, then
**Add custom connector**.
Workspace members: if your Owner already added AgentBank, select it and
skip to **Sign in**.
Name the connector **AgentBank** and enter:
```text theme={null}
https://mcp.useagentbank.com
```
Select **Add**.
Select **Connect** and complete AgentBank's browser sign-in. Choose your
account and review the requested permissions.
In a chat, select **+ → Connectors** and enable AgentBank. Ask:
```text theme={null}
Check my AgentBank account and wallet. Tell me if any setup is still needed.
```
Confirm that the connected account is yours.
Continue with [Your first payment](/getting-started/first-payment) or
[Example prompts](/ai-guides/conversation-patterns).
Add AgentBank in **Organization settings → Connectors → Add → Custom → Web**
using the server URL above. Each member then connects their own AgentBank
account under **Customize → Connectors**.
Check your plan and workspace permissions if you cannot add a connector.
Use exactly `https://mcp.useagentbank.com` without adding `/mcp`, and complete browser
sign-in. Enable AgentBank for the current conversation.
If a payment card is missing, ask Claude to reopen it or provide the
available action link.
For Claude Desktop's device-based installation, use the
[local MCP setup](/getting-started/connect-your-agent).
# Disconnect an agent
Source: https://docs.useagentbank.com/security/account-revocation
Remove access for a lost, compromised, or no-longer-needed agent.
Disconnect an agent when you no longer want it to use your AgentBank account.
## ChatGPT and Claude remote connections
Revoke the connection from AgentBank connection settings. You can also remove
the plugin or connector from the AI client's settings.
## Local agents
Ask the connected agent:
```text theme={null}
Disconnect this agent from AgentBank. Explain the effect and ask me to confirm before revoking access.
```
After confirmation, revocation invalidates that installation's access and wallet
authorization and clears its locally stored AgentBank credentials. Reconnecting
requires a new browser authorization.
If the device is lost or the agent is unavailable, use
[app.useagentbank.com](https://app.useagentbank.com) to manage access or
[contact support](/support/contact).
Revocation stops that agent's access; it is not a cancellation or refund for a
payment already funded. Check [Payment status and tracking](/payments/track-payments)
for any payment in progress.
# Security and wallet control
Source: https://docs.useagentbank.com/security/security-model
Understand wallet custody, agent permissions, and how to protect your account.
## Who controls your wallet?
Your AgentBank wallet is tied to your login and uses Privy wallet infrastructure.
You and the agents you authorize can operate it through the permissions granted
to them.
AgentBank does not take custody of your wallet funds. Payment and banking
partners may receive or process funds while completing a supported payment.
## Control agent access
Connect only the agents you want to use and review the permissions requested
during sign-in. Set an [approval threshold](/autonomy/configure-thresholds)
appropriate for that agent, and [disconnect unused or compromised agents](/security/account-revocation).
For ChatGPT and Claude, [spending grants](/autonomy/spending-grants) are a
separate, limited crypto-funding permission. Review their scope, limits, and expiry.
## Protect your payments
Review the recipient, currencies, amounts, and fees before confirming.
Use the funding instructions for that specific payment and ask for its status
if anything is unclear. A pending payment should be tracked rather than paid again.
Keep wallet keys, seed phrases, sign-in tokens, and World ID proofs out of
chat and support messages. Complete sign-in, identity checks, and wallet
approval through the browser flow provided by AgentBank.
If funds have moved and a payment fails, [contact support](/support/contact)
before attempting another transfer.
Builders can read [MCP configuration](/reference/configuration) for local
credential storage and profile isolation.
# Contact support
Source: https://docs.useagentbank.com/support/contact
Contact AgentBank support and share only safe diagnostic information.
[support@useagentbank.com](mailto:support@useagentbank.com)
Join the AgentBank support Telegram.
## Include when relevant
* payment ID;
* connected-agent installation ID when safely available;
* request ID;
* transaction hash;
* current payment status;
* timestamp and environment;
* redacted screenshot of the error.
Never share private keys, seed phrases, AgentBank session tokens, Privy access
or refresh tokens, authorization keys, or World ID proofs.
# FAQ
Source: https://docs.useagentbank.com/support/faq
Quick answers about AgentBank wallets, approvals, collections, and payment status.
No. Sign in at [app.useagentbank.com](https://app.useagentbank.com) and use
AgentBank's own chat. You can also [connect another assistant](/getting-started/quickstart).
AgentBank does not take custody of your wallet funds. Privy provides the
wallet infrastructure; payment partners may process funds during a payment.
See [Security and wallet control](/security/security-model).
Your threshold and the current payment policy determine whether World ID
approval is needed. Separate funding confirmation may still apply.
See [Autonomy and human control](/autonomy/overview).
Yes. Share the order-specific bank or QR instructions, or a shareable link
when the remote connection offers one. AgentBank can track whether the
payment was paid, but cannot identify who paid it.
Remote MCP can return a shareable action link when one is available for
the payment. Otherwise, use the returned bank or QR instructions.
Do not assume every payment supports a public link.
No. Ask your agent to check the final AgentBank payment status.
See [Payment status and tracking](/payments/track-payments).
Yes. A [payment plan](/payments/payment-plans) provides one consolidated
review and one World ID approval when required. Payments are funded and
settled individually.
Yes. [Staging](/getting-started/environment#staging) uses mock tokens.
A supported staging on-ramp completes automatically.
# Troubleshooting
Source: https://docs.useagentbank.com/support/troubleshooting
Find the next step for connection, verification, and payment problems.
In ChatGPT or Claude, check that AgentBank is connected and enabled in the
current conversation. For a local agent, check its configuration and
restart or reload the client. Follow your
[connection guide](/getting-started/quickstart).
Finish the AgentBank browser flow, then return to the same conversation.
Ask the agent to check the existing connection before starting setup again.
Never paste sign-in tokens into chat.
Complete the requested browser checks and wait for the result.
A submitted identity check may still need review for the selected currency.
See [Identity verification](/autonomy/kyc).
Provide the missing details requested by the agent and review the recipient
before confirming. For a screenshot containing only text, paste the bank
details as text; QR images must contain a readable QR code.
Ask for an updated quote and review the new amounts and fees before
confirming. If a payment already exists, ask the agent to check it first.
Ask the agent to track the existing payment. Do not pay again just because
payment detection or delivery is pending. See
[Payment status and tracking](/payments/track-payments).
Ask the assistant to reopen the card for the existing payment or provide
the available action link. See [Payment cards](/payments/hosted-payment-cards).
Ask the agent to check whether funds moved and what recovery is available
before creating another payment. See [Recover a payment](/payments/recover-failures).
If you already paid, contact support before sending more money.
For local credential errors and tool-level recovery, see
[MCP troubleshooting](/reference/troubleshooting).