Agentic global business accounts
Instant. No production account. No real money.
Keys Treat them like passwords. Scope the key to what the agent needs. Never commit them.
If you add another business in the web app, the entity name must be New Business Sandbox or Sandbox Business. Any other name stays In review.
Docs MCP first. No account. Then developer MCP to call the APIs.
| MCP | Auth | Use |
|---|---|---|
| Docs MCP | None | Docs. No account. |
| Developer MCP | Sandbox login | API calls. |
| AgentOS | Sandbox or production | Skills plus MCP. |
Coding tools
Docs MCP
claude mcp add-json airwallex-docs '{ "type": "http", "url": "https://mcp.sandbox.airwallex.com/docs" }'
Developer MCP
claude mcp add-json airwallex-dev '{ "type": "http", "url": "https://mcp.sandbox.airwallex.com/developer" }'
claude plugin install airwallex-agentos@claude-plugins-official
{
"mcpServers": {
"airwallex-docs": {
"type": "http",
"url": "https://mcp.sandbox.airwallex.com/docs"
},
"airwallex-dev": {
"type": "http",
"url": "https://mcp.sandbox.airwallex.com/developer"
}
}
}
AgentOS: Settings > Plugins > Marketplace, search airwallex.
experimental_use_rmcp_client = true [mcp_servers.airwallex_docs] url = "https://mcp.sandbox.airwallex.com/docs" [mcp_servers.airwallex_dev] url = "https://mcp.sandbox.airwallex.com/developer"
{
"mcpServers": {
"airwallex-docs": {
"httpUrl": "https://mcp.sandbox.airwallex.com/docs"
},
"airwallex-dev": {
"httpUrl": "https://mcp.sandbox.airwallex.com/developer"
}
}
}
{
"mcpServers": {
"airwallex-docs": {
"serverUrl": "https://mcp.sandbox.airwallex.com/docs"
},
"airwallex-dev": {
"serverUrl": "https://mcp.sandbox.airwallex.com/developer"
}
}
}
REST auth
For agents not using developer MCP.
Sandbox: https://api.sandbox.airwallex.com POST /api/v1/authentication/login Headers: x-client-id, x-api-key. No body. Then: Authorization: Bearer <token> Token lasts 30 minutes. Re-login when it expires. Amounts are major units. 100 is one hundred dollars. Connected accounts (briefs 05-08): x-on-behalf-of: <account_id>
Simulation
Fake deposits, card charges, and transfer outcomes.
POST /api/v1/simulation/deposit/create
POST /api/v1/simulation/issuing/create
POST /api/v1/simulation/issuing/{id}/capture
POST /api/v1/simulation/transfers/{id}/transition
Transfers: FAILED auto-cancels in seconds, so a slow poll can miss it and lose failure_reason. Branch on FAILED and CANCELLED.
Cards: don't wait for APPROVED on demo timescales. AUTHORIZATION plus PENDING means funds reserved. CLEARING plus APPROVED means funds debited. CLEARING plus FAILED means declined.
Rest in sandbox docs.
Webhooks
Web app, not the API. Tunnel localhost for local dev.
Settings > Developer > Webhooks in the sandbox web app, not the API. Copy the Webhook Secret shown when you create the subscription. Delivery: x-timestamp and x-signature. HMAC-SHA256 of x-timestamp plus the raw body, secret as key. Events can arrive twice and out of order. Dedupe on event id, sort by created_at, return 200 or Airwallex retries for about three days.
Expected events: payout.transfer.paid, payout.transfer.failed, payout.transfer.cancelled.
issuing.transaction.succeeded, issuing.transaction.failed.
Ask the agent to list global accounts. An empty list means you're connected.
List global accounts
List global accounts.
Expected The agent calls Developer MCP. An empty list is a connection. If it fails, say what's missing: docs MCP, developer MCP, or sandbox login.
REST login
POST /api/v1/authentication/login Headers: x-client-id, x-api-key. No body. Then: Authorization: Bearer <token> Token lasts 30 minutes. Re-login when it expires.
Expected 200 with a Bearer token. Valid 30 minutes. No token means credentials or scoping.
First prompt
You're building with Airwallex sandbox APIs. Airwallex offers agentic global business accounts: payments, remittances, treasury, spend, cards, FX, and multi-currency wallets. Sandbox only. No production. No real money. Use these MCP servers if they're connected: Docs (no login): https://mcp.sandbox.airwallex.com/docs Developer (sandbox login): https://mcp.sandbox.airwallex.com/developer If developer MCP asks you to sign in, use the user's sandbox account. Mutating calls need a stable request_id. Reuse it when you retry. Generate a new one when you mean a new payment. Amounts are major units, not cents. 100 is one hundred dollars. First task: list global accounts. If none, create one, then simulate a deposit. Then list sandbox wallet balances. If you can't, say what's missing: docs MCP, developer MCP, sandbox login, or a global account.
If the list from Verify is empty, create. Then simulate a deposit.
If Verify returned accounts, skip to deposit. If the list was empty, create one. Developer MCP cannot create a Global Account.
1. Create if empty
country_code is the account country, not the currency. NL, DE, or FR for EUR. BE is rejected. required_features is objects, not strings.
POST /api/v1/global_accounts/create
{
"request_id": "<unique>",
"country_code": "US",
"required_features": [{ "currency": "USD", "transfer_method": "LOCAL" }]
}
2. Simulate deposit
Amounts are major units. 25000 is twenty-five thousand dollars. The balance is available immediately even if the response says PENDING.
POST /api/v1/simulation/deposit/create
{
"global_account_id": "<id>",
"amount": 25000,
"payer_name": "Seed funding"
}
3. Simulate transaction
Test card 4035501000000008, any future expiry, any CVC. Micro-deposits 0.01 and 0.02.
If create or deposit fails Stop. Don't paste a library brief yet. Check the entity is not In review, then REST auth in Connect your tools.
Paste a brief into your coding agent.