Airwallex Best Practices
Fallback skill for Airwallex tasks. Use only when no dedicated workflow skill fits. Each workflow skill (beneficiary-creation, card-provisioning, contract-to-billing, manage-cashflow) is self-contained — do NOT load this skill alongside them.
When to use
- Ad-hoc operations (list, get, update, delete, void, cancel, deactivate)
- General Airwallex API questions or troubleshooting
- Payment links, refunds, disputes, spend management, financial reports, and other domains not covered by a dedicated workflow skill
Use a workflow skill instead
| Task |
Skill |
| Create invoice from PO/contract/quote |
contract-to-billing |
| Coupons, meters, usage events, credit notes |
contract-to-billing |
| Onboard suppliers / create beneficiaries |
beneficiary-creation |
| Provision corporate cards |
card-provisioning |
| Cash position, FX, balances, rebalancing |
manage-cashflow |
If a workflow skill matches, use that skill instead — do NOT load this one alongside it.
Out of scope — refuse and redirect
Do NOT attempt to fulfill these by aggregating API calls. State plainly that the capability is not available, explain the closest alternative, and offer to help with it.
| Request pattern |
Why out of scope |
Redirect |
| "Forecast", "hedging strategy", "FX prediction" |
Agent provides indicative spot rates only |
Offer manage-cashflow for current exposure and indicative FX rates |
| "Yield", "investment advice", "idle funds", "automated top-up", "should I lock a rate?" |
Financial advice or unsupported treasury action |
Offer manage-cashflow for current balances, obligations, and informational indicative FX only |
Environment quickstart
See references/surface-quickstart.md for full per-surface details (auth, discovery, write safety, pagination, error handling).
Operational rules
- NEVER fabricate or assume missing information. If any required field is uncertain — STOP and ask the user.
- Always fetch fresh data — re-fetch before every step.
- If the user supplied a file or attachment, treat it as primary ground truth unless they ask for live data.
- For ambiguous-intent requests, confirm the action before starting.
- Never overclaim unsupported capabilities. Transfers, payouts, FX execution, PAN/CVV retrieval: refuse immediately, state what is not available, offer the closest alternative.
- Do not provide financial advice. Never recommend yield, investment products, automated top-ups, hedging strategy, FX prediction, or rate-locking. For treasury questions, redirect to manage-cashflow and keep any FX discussion informational and clearly labelled as indicative.
- Split supported and unsupported asks. Complete the supported portion and clearly state what was not configured.
- Prefer business labels over raw IDs in user-facing output. Show human-readable business labels (customer names, product names, beneficiary names, card nicknames, etc.) instead of raw system IDs whenever possible. Only show IDs when they are operationally necessary for follow-up actions, verification, troubleshooting, or when the user explicitly asks for them.
Core Airwallex concepts
- One wallet, multiple currencies. Say "AUD balance" — never "AUD wallet."
- Invoices = receivables (money in). Issued BY the user TO their customers.
- Bills = payables (money out). Money the user owes to suppliers.
- FX conversions happen within one wallet — not between wallets.
Consequential operations
These are irreversible or high-impact. Before executing ANY of them: (1) confirm and state the environment (sandbox vs production), (2) explain the effect, (3) get explicit user confirmation.
| Operation |
CLI |
MCP |
Notes |
| Void invoice |
airwallex --confirm invoices void <id> |
invoke the billing-invoice void tool |
Irreversible. FINALIZED+UNPAID only. |
| Delete draft invoice |
airwallex --confirm invoices delete <id> |
not exposed |
DRAFT only. |
| Finalize invoice |
airwallex --confirm invoices finalize <id> |
invoke the billing-invoice finalize tool |
Irreversible — cannot edit after. |
| Mark invoice paid |
airwallex --confirm invoices mark-as-paid <id> |
invoke the billing-invoice mark-as-paid tool |
Must be FINALIZED. Use when paid outside Airwallex. |
| Cancel subscription |
airwallex --confirm subscriptions cancel <id> |
invoke the subscription cancel tool |
Check flags via schema. |
| Deactivate card |
cards update <id> body {"status":"INACTIVE"} |
card-update tool with card_status: INACTIVE |
Reversible. See references/api_traps.md for which statuses are NOT settable here. |
| Close card |
cards update <id> body {"status":"CLOSED"} |
card-update tool with card_status: CLOSED |
Permanent. |
| FX conversion |
Airwallex Dashboard only |
Airwallex Dashboard only |
Not executable via either surface. |
| Finalize credit note |
airwallex --confirm credit-notes finalize <id> |
credit-note tools not exposed — use the CLI or the Airwallex Dashboard |
Irreversible. |
| Void credit note |
airwallex --confirm credit-notes void <id> |
credit-note tools not exposed — use the CLI or the Airwallex Dashboard |
Irreversible. |
| Close global account |
airwallex --confirm global-accounts close <id> |
invoke the global-account close tool if exposed |
Permanent. |
| Delete cardholder |
airwallex --confirm cardholders delete <id> |
invoke the cardholder delete tool if exposed |
Ensure no active cards. |
Error handling
| Situation |
Action |
| Required field missing or ambiguous |
STOP, list gaps, ask user |
| API error |
Show full error, ask user |
| API validation error |
Check references/api_traps.md. IF using the CLI, THEN also run airwallex <resource> <action> --api-schema-only to verify body structure. ELSE IF using the MCP server, THEN re-inspect the tool's input schema. |
| 401 / auth expired |
IF using the CLI, THEN retry once (auto-refresh). If retry fails, ask the user which environment, immediately execute auth login (or --prod) yourself, confirm with auth whoami, then resume. ELSE IF using the MCP server, THEN the server refreshes tokens automatically; if a tool keeps returning 401, the OAuth grant has been revoked — ask the user to re-authorize the MCP server. |
| Duplicate detected |
Show details, let user choose |
| Partial completion |
Report what succeeded (with IDs) and what failed |
References
- references/api_traps.md — non-obvious body constraints beyond what the schema/manifest surfaces.
- IF using the CLI, THEN
airwallex --tree --compact [group] for command discovery and airwallex <resource> <action> --api-schema-only for command schemas (including required flags).
- Airwallex API Introduction
Feedback
When the user reacts to how this skill performed (praise, frustration, a gap, a missing capability) — or when you hit a real gap, unclear/wrong instruction, or unexpected behavior while using it — briefly offer to pass feedback along and, on the user's go-ahead, submit it. See references/feedback.md for when to offer, the channel commands (CLI / MCP), and the rules (ask first, no sensitive data, don't nag).
1---2name: awx-best-practices3description: Fallback Airwallex skill — works with the Airwallex CLI or the Airwallex MCP server. Use ONLY when no dedicated workflow skill matches the task. Covers ad-hoc operations (list, get, update, delete, void, cancel), general Airwallex API questions, troubleshooting, and domains not covered by a workflow skill (payment links, refunds, disputes, spend management, financial reports). Do NOT load this skill alongside a workflow skill — each workflow skill is self-contained. For invoices/billing/coupons/meters/credit notes use contract-to-billing, for suppliers/beneficiaries use beneficiary-creation, for cards use card-provisioning, for balances/FX/cashflow use manage-cashflow.4---56# Airwallex Best Practices78Fallback skill for Airwallex tasks. **Use only when no dedicated workflow skill fits.** Each workflow skill (beneficiary-creation, card-provisioning, contract-to-billing, manage-cashflow) is self-contained — do NOT load this skill alongside them.910## When to use1112- Ad-hoc operations (list, get, update, delete, void, cancel, deactivate)13- General Airwallex API questions or troubleshooting14- Payment links, refunds, disputes, spend management, financial reports, and other domains not covered by a dedicated workflow skill1516## Use a workflow skill instead1718| Task | Skill |19| --- | --- |20| Create invoice from PO/contract/quote | **contract-to-billing** |21| Coupons, meters, usage events, credit notes | **contract-to-billing** |22| Onboard suppliers / create beneficiaries | **beneficiary-creation** |23| Provision corporate cards | **card-provisioning** |24| Cash position, FX, balances, rebalancing | **manage-cashflow** |2526If a workflow skill matches, use that skill instead — do NOT load this one alongside it.2728## Out of scope — refuse and redirect2930Do NOT attempt to fulfill these by aggregating API calls. State plainly that the capability is not available, explain the closest alternative, and offer to help with it.3132| Request pattern | Why out of scope | Redirect |33| --- | --- | --- |34| "Forecast", "hedging strategy", "FX prediction" | Agent provides indicative spot rates only | Offer **manage-cashflow** for current exposure and indicative FX rates |35| "Yield", "investment advice", "idle funds", "automated top-up", "should I lock a rate?" | Financial advice or unsupported treasury action | Offer **manage-cashflow** for current balances, obligations, and informational indicative FX only |3637---3839## Environment quickstart4041See [references/surface-quickstart.md](references/surface-quickstart.md) for full per-surface details (auth, discovery, write safety, pagination, error handling).4243---4445## Operational rules4647- **NEVER fabricate or assume missing information.** If any required field is uncertain — STOP and ask the user.48- **Always fetch fresh data** — re-fetch before every step.49- **If the user supplied a file or attachment, treat it as primary ground truth** unless they ask for live data.50- **For ambiguous-intent requests, confirm the action before starting.**51- **Never overclaim unsupported capabilities.** Transfers, payouts, FX execution, PAN/CVV retrieval: refuse immediately, state what is not available, offer the closest alternative.52- **Do not provide financial advice.** Never recommend yield, investment products, automated top-ups, hedging strategy, FX prediction, or rate-locking. For treasury questions, redirect to **manage-cashflow** and keep any FX discussion informational and clearly labelled as indicative.53- **Split supported and unsupported asks.** Complete the supported portion and clearly state what was not configured.54- **Prefer business labels over raw IDs in user-facing output.** Show human-readable business labels (customer names, product names, beneficiary names, card nicknames, etc.) instead of raw system IDs whenever possible. Only show IDs when they are operationally necessary for follow-up actions, verification, troubleshooting, or when the user explicitly asks for them.5556## Core Airwallex concepts5758- **One wallet, multiple currencies.** Say "AUD balance" — never "AUD wallet."59- **Invoices = receivables (money in).** Issued BY the user TO their customers.60- **Bills = payables (money out).** Money the user owes to suppliers.61- **FX conversions happen within one wallet** — not between wallets.6263---6465## Consequential operations6667These are **irreversible or high-impact**. Before executing ANY of them: (1) confirm and state the environment (sandbox vs production), (2) explain the effect, (3) get explicit user confirmation.6869| Operation | CLI | MCP | Notes |70| --- | --- | --- | --- |71| Void invoice | `airwallex --confirm invoices void <id>` | invoke the billing-invoice void tool | Irreversible. FINALIZED+UNPAID only. |72| Delete draft invoice | `airwallex --confirm invoices delete <id>` | _not exposed_ | DRAFT only. |73| Finalize invoice | `airwallex --confirm invoices finalize <id>` | invoke the billing-invoice finalize tool | Irreversible — cannot edit after. |74| Mark invoice paid | `airwallex --confirm invoices mark-as-paid <id>` | invoke the billing-invoice mark-as-paid tool | Must be FINALIZED. Use when paid outside Airwallex. |75| Cancel subscription | `airwallex --confirm subscriptions cancel <id>` | invoke the subscription cancel tool | Check flags via schema. |76| Deactivate card | `cards update <id>` body `{"status":"INACTIVE"}` | card-update tool with `card_status: INACTIVE` | Reversible. See [references/api_traps.md](references/api_traps.md) for which statuses are NOT settable here. |77| Close card | `cards update <id>` body `{"status":"CLOSED"}` | card-update tool with `card_status: CLOSED` | **Permanent.** |78| FX conversion | **Airwallex Dashboard only** | **Airwallex Dashboard only** | Not executable via either surface. |79| Finalize credit note | `airwallex --confirm credit-notes finalize <id>` | _credit-note tools not exposed — use the CLI or the Airwallex Dashboard_ | Irreversible. |80| Void credit note | `airwallex --confirm credit-notes void <id>` | _credit-note tools not exposed — use the CLI or the Airwallex Dashboard_ | Irreversible. |81| Close global account | `airwallex --confirm global-accounts close <id>` | invoke the global-account close tool if exposed | **Permanent.** |82| Delete cardholder | `airwallex --confirm cardholders delete <id>` | invoke the cardholder delete tool if exposed | Ensure no active cards. |8384---8586## Error handling8788| Situation | Action |89| --- | --- |90| Required field missing or ambiguous | STOP, list gaps, ask user |91| API error | Show full error, ask user |92| API validation error | Check [references/api_traps.md](references/api_traps.md). **IF** using the CLI, **THEN** also run `airwallex <resource> <action> --api-schema-only` to verify body structure. **ELSE IF** using the MCP server, **THEN** re-inspect the tool's input schema. |93| 401 / auth expired | **IF** using the CLI, **THEN** retry once (auto-refresh). If retry fails, ask the user which environment, immediately execute `auth login` (or `--prod`) yourself, confirm with `auth whoami`, then resume. **ELSE IF** using the MCP server, **THEN** the server refreshes tokens automatically; if a tool keeps returning 401, the OAuth grant has been revoked — ask the user to re-authorize the MCP server. |94| Duplicate detected | Show details, let user choose |95| Partial completion | Report what succeeded (with IDs) and what failed |9697## References9899- [references/api_traps.md](references/api_traps.md) — non-obvious body constraints beyond what the schema/manifest surfaces.100- **IF** using the CLI, **THEN** `airwallex --tree --compact [group]` for command discovery and `airwallex <resource> <action> --api-schema-only` for command schemas (including required flags).101- [Airwallex API Introduction](https://www.airwallex.com/docs/api/introduction)102103## Feedback104105When the user reacts to how this skill performed (praise, frustration, a gap, a missing capability) — or when you hit a real gap, unclear/wrong instruction, or unexpected behavior while using it — briefly offer to pass feedback along and, on the user's go-ahead, submit it. See [references/feedback.md](../../references/feedback.md) for when to offer, the channel commands (CLI / MCP), and the rules (ask first, no sensitive data, don't nag).
AgentCorp-Inc