SwapEazi is the AI agent for managing cross-border payments.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Where the money leaks on your current provider: total cost against the official rate in money and bps, split into FX spread and fees, and the estimated saving against the recommended eligible route (ESTIMATED, never realised). Needs existing_provider. One analysis (POST /api/v1/payment-analyses), the same service for every payment-intelligence tool. Every figure labelled LIVE, INDICATIVE, HISTORICAL or ESTIMATED; estimated savings are never realised. Free: shares the route-assessment allowance.
Amount, in currency (default the source currency).
Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1.
The currency of amount: the source currency, or the destination one (then it is what the supplier receives).
YYYY-MM-DD: a route that cannot settle by then is not eligible.
Sets the default scoring weights. Default balanced.
A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted.
Read a kept analysis (pa_...) instead of making a new one.
Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below.
ISO code you pay from, e.g. EUR or ZAR.
Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }.
What the supplier must receive, in the destination currency (instead of amount).
ISO 3166 alpha-2 or name, e.g. ZM or Mozambique.
ISO code the supplier is paid in, e.g. ZMW. Or destination_country.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Pick your client. Values in capitals, like YOUR_TOKEN, are yours to fill in.
Run in a terminal
claude mcp add --transport http swapeazi https://swapeazi.io/api/mcp
Where the money leaks on your current provider: total cost against the official rate in money and bps, split into FX spread and fees, and the estimated saving against the recommended eligible route (ESTIMATED, never realised). Needs existing_provider. One analysis (POST /api/v1/payment-analyses), the same service for every payment-intelligence tool. Every figure labelled LIVE, INDICATIVE, HISTORICAL or ESTIMATED; estimated savings are never realised. Free: shares the route-assessment allowance.
| Argument | Type | Description |
|---|---|---|
| amount | number | Amount, in currency (default the source currency). |
| weights | object | Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1. |
| currency | string | The currency of amount: the source currency, or the destination one (then it is what the supplier receives). |
| due_date | string | YYYY-MM-DD: a route that cannot settle by then is not eligible. |
| priority | string | Sets the default scoring weights. Default balanced. |
| supplier | string | |
| reference | string | |
| access_key | string | A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted. |
| analysis_id | string | Read a kept analysis (pa_...) instead of making a new one. |
| invoice_text | string | Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below. |
| source_currency | string | ISO code you pay from, e.g. EUR or ZAR. |
| existing_provider | object | Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }. |
| beneficiary_amount | number | What the supplier must receive, in the destination currency (instead of amount). |
| destination_country | string | ISO 3166 alpha-2 or name, e.g. ZM or Mozambique. |
| destination_currency | string | ISO code the supplier is paid in, e.g. ZMW. Or destination_country. |
{
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount, in currency (default the source currency)."
},
"weights": {
"type": "object",
"description": "Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1."
},
"currency": {
"type": "string",
"description": "The currency of amount: the source currency, or the destination one (then it is what the supplier receives)."
},
"due_date": {
"type": "string",
"description": "YYYY-MM-DD: a route that cannot settle by then is not eligible."
},
"priority": {
"enum": [
"cost",
"speed",
"balanced"
],
"type": "string",
"description": "Sets the default scoring weights. Default balanced."
},
"supplier": {
"type": "string"
},
"reference": {
"type": "string"
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted."
},
"analysis_id": {
"type": "string",
"description": "Read a kept analysis (pa_...) instead of making a new one."
},
"invoice_text": {
"type": "string",
"description": "Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below."
},
"source_currency": {
"type": "string",
"description": "ISO code you pay from, e.g. EUR or ZAR."
},
"existing_provider": {
"type": "object",
"description": "Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }."
},
"beneficiary_amount": {
"type": "number",
"description": "What the supplier must receive, in the destination currency (instead of amount)."
},
"destination_country": {
"type": "string",
"description": "ISO 3166 alpha-2 or name, e.g. ZM or Mozambique."
},
"destination_currency": {
"type": "string",
"description": "ISO code the supplier is paid in, e.g. ZMW. Or destination_country."
}
}
}Read a payout the agent held for approval by approval_id: awaiting_approval while it is pending; approved with the agent_approval { id, role } to pass to record_release; rejected with the approver's reason; or expired once its release-by date passed undecided. Each decision is signed and chained to the agent's decision record. Do not release a payout while it is awaiting approval, rejected or expired. Read-only. Needs the organisation's key; demo items (aprd_) do not.
| Argument | Type | Description |
|---|---|---|
| approval_id* | string | apr_… (or aprd_… for a demo item), from POST /api/v1/agent/run with policy_id. |
{
"type": "object",
"required": [
"approval_id"
],
"properties": {
"approval_id": {
"type": "string",
"description": "apr_… (or aprd_… for a demo item), from POST /api/v1/agent/run with policy_id."
}
}
}Records the approval of a named person (approver: { name, role }) for the run's prepared payments (payments: "all_prepared") or listed payment_ids (held ones need acknowledge: true), and creates one release record per approved payment. Each approved payment returns release_in_own_bank: beneficiary, amount, currency, reference, which of the business's own accounts to pay from and the cut-off, for the business to release itself in its own bank or rail portal; then record what landed with reconcile_payment. An agent cannot approve on its own: this tool records an approval only when the run's policy sets agent_may_record_approval and names the person who approved; otherwise it returns how the person approves (POST /api/v1/payment-runs/{id}/approve). Never sends or moves money.
| Argument | Type | Description |
|---|---|---|
| run_id* | string | pr_... or pr_sample. |
| approver* | object | { name, role, id? }: the person who approved. Required. |
| payments | any | "all_prepared" or a list of payment_ids. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
| acknowledge | boolean | true to approve listed payments that need attention or have no evidence, once the person has assessed them. |
{
"type": "object",
"required": [
"run_id",
"approver"
],
"properties": {
"run_id": {
"type": "string",
"description": "pr_... or pr_sample."
},
"approver": {
"type": "object",
"description": "{ name, role, id? }: the person who approved. Required."
},
"payments": {
"description": "\"all_prepared\" or a list of payment_ids."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
},
"acknowledge": {
"type": "boolean",
"description": "true to approve listed payments that need attention or have no evidence, once the person has assessed them."
}
}
}Before a business commits to a cross-border payment, assess the corridor on SwapEazi's independent data. Returns deterministic JSON: the routes known for the pair, each cost and FX figure with its source, read time, freshness (fresh, aging, stale, unknown) and evidence type (observed, executable, indicative, published; the official rate as reference), settlement facts, the requirements on record with sources, what changed since the last assessment of the corridor, data-quality flags (stale, contradictory, missing, indicative only), unknowns, and the evidence behind each finding, under an assessment_id whose record is kept and retrievable (GET /api/v1/route-assessments/{id}; a content hash, not a signature). Never ranks a route as advice, never executes, never claims a figure is executable unless a provider's firm quote is on record. Free; same as GET /api/v1/route-assessments.
| Argument | Type | Description |
|---|---|---|
| to | string | Destination currency, ISO code, e.g. ZMW. |
| from | string | Source currency, ISO code, e.g. EUR. |
| sort | string | Your chosen order for the routes: landed cost against the official rate, stated days to land, or the measured 7-day answer rate. It is your order, stated as yours; SwapEazi does not rank routes. |
| as_of | string | Assessment time, ISO 8601, within 15 minutes of now (default now). A past assessment is retrieved by assessment_id, never recomputed. |
| amount | number | Amount leaving, in the source currency. Optional: without it the corridor is assessed at about USD 10,000, labelled. |
| corridor | string | Instead of from and to: e.g. EUR-ZMW. |
| assessment_id | string | Retrieve a kept assessment record instead of making a new one. |
| exclude_types | array | Leave out routes of these rail types. Each route left out is listed with the reason. |
| include_types | array | Keep only routes of these rail types. Each route left out is listed with the reason. |
| min_answer_rate | number | Percent, 0 to 100: leave out routes whose measured 7-day answer rate is lower, or not measured (not enough reads). Each is listed with the reason. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "Destination currency, ISO code, e.g. ZMW."
},
"from": {
"type": "string",
"description": "Source currency, ISO code, e.g. EUR."
},
"sort": {
"enum": [
"landed_cost",
"arrival_time",
"answer_rate"
],
"type": "string",
"description": "Your chosen order for the routes: landed cost against the official rate, stated days to land, or the measured 7-day answer rate. It is your order, stated as yours; SwapEazi does not rank routes."
},
"as_of": {
"type": "string",
"description": "Assessment time, ISO 8601, within 15 minutes of now (default now). A past assessment is retrieved by assessment_id, never recomputed."
},
"amount": {
"type": "number",
"description": "Amount leaving, in the source currency. Optional: without it the corridor is assessed at about USD 10,000, labelled."
},
"corridor": {
"type": "string",
"description": "Instead of from and to: e.g. EUR-ZMW."
},
"assessment_id": {
"type": "string",
"description": "Retrieve a kept assessment record instead of making a new one."
},
"exclude_types": {
"type": "array",
"items": {
"enum": [
"banks",
"otc_desks",
"exchange_books",
"stablecoin_pools",
"p2p",
"ramps",
"payment_providers"
],
"type": "string"
},
"description": "Leave out routes of these rail types. Each route left out is listed with the reason."
},
"include_types": {
"type": "array",
"items": {
"enum": [
"banks",
"otc_desks",
"exchange_books",
"stablecoin_pools",
"p2p",
"ramps",
"payment_providers"
],
"type": "string"
},
"description": "Keep only routes of these rail types. Each route left out is listed with the reason."
},
"min_answer_rate": {
"type": "number",
"description": "Percent, 0 to 100: leave out routes whose measured 7-day answer rate is lower, or not measured (not enough reads). Each is listed with the reason."
}
}
}What this payment costs through your current provider against the official rate: effective rate, FX spread, transaction, intermediary and payout fees, total cost in money and bps, and what the beneficiary receives; with each alternative route's cost at the same size. One analysis (POST /api/v1/payment-analyses), the same service for every payment-intelligence tool. Every figure labelled LIVE, INDICATIVE, HISTORICAL or ESTIMATED; estimated savings are never realised. Free: shares the route-assessment allowance.
| Argument | Type | Description |
|---|---|---|
| amount | number | Amount, in currency (default the source currency). |
| weights | object | Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1. |
| currency | string | The currency of amount: the source currency, or the destination one (then it is what the supplier receives). |
| due_date | string | YYYY-MM-DD: a route that cannot settle by then is not eligible. |
| priority | string | Sets the default scoring weights. Default balanced. |
| supplier | string | |
| reference | string | |
| access_key | string | A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted. |
| analysis_id | string | Read a kept analysis (pa_...) instead of making a new one. |
| invoice_text | string | Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below. |
| source_currency | string | ISO code you pay from, e.g. EUR or ZAR. |
| existing_provider | object | Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }. |
| beneficiary_amount | number | What the supplier must receive, in the destination currency (instead of amount). |
| destination_country | string | ISO 3166 alpha-2 or name, e.g. ZM or Mozambique. |
| destination_currency | string | ISO code the supplier is paid in, e.g. ZMW. Or destination_country. |
{
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount, in currency (default the source currency)."
},
"weights": {
"type": "object",
"description": "Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1."
},
"currency": {
"type": "string",
"description": "The currency of amount: the source currency, or the destination one (then it is what the supplier receives)."
},
"due_date": {
"type": "string",
"description": "YYYY-MM-DD: a route that cannot settle by then is not eligible."
},
"priority": {
"enum": [
"cost",
"speed",
"balanced"
],
"type": "string",
"description": "Sets the default scoring weights. Default balanced."
},
"supplier": {
"type": "string"
},
"reference": {
"type": "string"
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted."
},
"analysis_id": {
"type": "string",
"description": "Read a kept analysis (pa_...) instead of making a new one."
},
"invoice_text": {
"type": "string",
"description": "Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below."
},
"source_currency": {
"type": "string",
"description": "ISO code you pay from, e.g. EUR or ZAR."
},
"existing_provider": {
"type": "object",
"description": "Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }."
},
"beneficiary_amount": {
"type": "number",
"description": "What the supplier must receive, in the destination currency (instead of amount)."
},
"destination_country": {
"type": "string",
"description": "ISO 3166 alpha-2 or name, e.g. ZM or Mozambique."
},
"destination_currency": {
"type": "string",
"description": "ISO code the supplier is paid in, e.g. ZMW. Or destination_country."
}
}
}Re-evaluate every candidate in a stored Options Map against constraints supplied now: the principal's own policy, an AP2 open (intent) mandate, a Verifiable Intent credential, or x402 payment requirements (accepts[] with the listed price, verified against the reference). Each row comes back inside, outside or unknown, and carries the map's own route_family, regulatory_risk and onboarding_status/onboarding_gap for that candidate, so an agent can drop ineligible or blocked rows without a second call. Nothing is executed or issued. Free.
| Argument | Type | Description |
|---|---|---|
| x402 | object | { accepts: PaymentRequirements[], price: { currency, amount } }. |
| map_id* | string | The map_id from map_options. |
| policy_id | string | A release policy of this organisation (needs its key): supplies the limit and the map-age rule. |
| ap2_mandate | object | An AP2 intent mandate; recognised fields are read, the rest listed as unevaluable. |
| constraints | object | max_all_in_bps_vs_ref, max_settlement_days, allowed_rail_classes, disallowed_providers, must_include_provider_id, allowed_providers (restrict every row to your own already-connected panel, by provider id or name — a candidate outside it evaluates outside, never hidden; for embedding this assessment as a mandatory step inside your own already-licensed payment run, the way an EMS asks which of its own connected brokers should carry an order), corporate_only. Stablecoin risk appetite, the client's own thresholds held to each token's dated profile (/stablecoins): stablecoin_attestation_max_age_days, stablecoin_peg_min_share_within_50bps (0 to 1, last 30 days), stablecoin_peg_max_worst_bps (last 30 days), stablecoin_exit_depth_covers_amount (true), stablecoin_supervised_in (ISO codes or EU), stablecoin_no_single_key_mint_freeze (true). A fact not on record makes the row unknown, never inside. |
| verifiable_intent | string | object | A Verifiable Intent credential: the serialised SD-JWT, or decoded mandate objects. Amount limits and expiry are held to the intent; where the payment crosses currencies, the result says the mandate does not bound the conversion cost. |
| instrument_classes_allowed | array |
{
"type": "object",
"required": [
"map_id"
],
"properties": {
"x402": {
"type": "object",
"description": "{ accepts: PaymentRequirements[], price: { currency, amount } }."
},
"map_id": {
"type": "string",
"description": "The map_id from map_options."
},
"policy_id": {
"type": "string",
"description": "A release policy of this organisation (needs its key): supplies the limit and the map-age rule."
},
"ap2_mandate": {
"type": "object",
"description": "An AP2 intent mandate; recognised fields are read, the rest listed as unevaluable."
},
"constraints": {
"type": "object",
"description": "max_all_in_bps_vs_ref, max_settlement_days, allowed_rail_classes, disallowed_providers, must_include_provider_id, allowed_providers (restrict every row to your own already-connected panel, by provider id or name — a candidate outside it evaluates outside, never hidden; for embedding this assessment as a mandatory step inside your own already-licensed payment run, the way an EMS asks which of its own connected brokers should carry an order), corporate_only. Stablecoin risk appetite, the client's own thresholds held to each token's dated profile (/stablecoins): stablecoin_attestation_max_age_days, stablecoin_peg_min_share_within_50bps (0 to 1, last 30 days), stablecoin_peg_max_worst_bps (last 30 days), stablecoin_exit_depth_covers_amount (true), stablecoin_supervised_in (ISO codes or EU), stablecoin_no_single_key_mint_freeze (true). A fact not on record makes the row unknown, never inside."
},
"verifiable_intent": {
"type": [
"string",
"object"
],
"description": "A Verifiable Intent credential: the serialised SD-JWT, or decoded mandate objects. Amount limits and expiry are held to the intent; where the payment crosses currencies, the result says the mandate does not bound the conversion cost."
},
"instrument_classes_allowed": {
"type": "array",
"items": {
"enum": [
"spot",
"forward",
"stablecoin_rail"
],
"type": "string"
}
}
}
}Verify one payment against a mandate before it is prepared. A breach returns mandate_violation and the rule that failed. A pass still needs the named person to approve. Nothing is sent. A router key is required. The verification is recorded when the payment is prepared inside a payment run.
| Argument | Type | Description |
|---|---|---|
| to* | string | |
| from* | string | |
| rail | string | |
| amount* | number | |
| agent_id | string | |
| currency* | string | |
| access_key | string | |
| mandate_id* | string | |
| cost_above_official_pct | number | null | Null when the gap to the official rate is not on record. Never treated as zero. |
{
"type": "object",
"required": [
"mandate_id",
"amount",
"currency",
"from",
"to"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"rail": {
"enum": [
"bank",
"provider",
"stablecoin"
],
"type": "string"
},
"amount": {
"type": "number"
},
"agent_id": {
"type": "string"
},
"currency": {
"type": "string"
},
"access_key": {
"type": "string"
},
"mandate_id": {
"type": "string"
},
"cost_above_official_pct": {
"type": [
"number",
"null"
],
"description": "Null when the gap to the official rate is not on record. Never treated as zero."
}
}
}Spec v1.0 name for liquidity_map: each venue type with whether the evidence read shows depth at the size, slippage and landing cost with a Rate Receipt, or Being measured with the reason. Same arguments as liquidity_map.
| Argument | Type | Description |
|---|---|---|
| to | string | |
| from | string | |
| pair | string | e.g. EUR-ZMW. Or from and to. |
| amount* | number | |
| access_key | string | |
| amount_currency | string |
{
"type": "object",
"required": [
"amount"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"pair": {
"type": "string",
"description": "e.g. EUR-ZMW. Or from and to."
},
"amount": {
"type": "number"
},
"access_key": {
"type": "string"
},
"amount_currency": {
"type": "string"
}
}
}Your current provider beside every route on record for the corridor at the same amount and against the same official rate: all-in bps, total cost, beneficiary amount, eligibility and score, plus routes known without figures. One analysis (POST /api/v1/payment-analyses), the same service for every payment-intelligence tool. Every figure labelled LIVE, INDICATIVE, HISTORICAL or ESTIMATED; estimated savings are never realised. Free: shares the route-assessment allowance.
| Argument | Type | Description |
|---|---|---|
| amount | number | Amount, in currency (default the source currency). |
| weights | object | Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1. |
| currency | string | The currency of amount: the source currency, or the destination one (then it is what the supplier receives). |
| due_date | string | YYYY-MM-DD: a route that cannot settle by then is not eligible. |
| priority | string | Sets the default scoring weights. Default balanced. |
| supplier | string | |
| reference | string | |
| access_key | string | A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted. |
| analysis_id | string | Read a kept analysis (pa_...) instead of making a new one. |
| invoice_text | string | Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below. |
| source_currency | string | ISO code you pay from, e.g. EUR or ZAR. |
| existing_provider | object | Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }. |
| beneficiary_amount | number | What the supplier must receive, in the destination currency (instead of amount). |
| destination_country | string | ISO 3166 alpha-2 or name, e.g. ZM or Mozambique. |
| destination_currency | string | ISO code the supplier is paid in, e.g. ZMW. Or destination_country. |
{
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount, in currency (default the source currency)."
},
"weights": {
"type": "object",
"description": "Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1."
},
"currency": {
"type": "string",
"description": "The currency of amount: the source currency, or the destination one (then it is what the supplier receives)."
},
"due_date": {
"type": "string",
"description": "YYYY-MM-DD: a route that cannot settle by then is not eligible."
},
"priority": {
"enum": [
"cost",
"speed",
"balanced"
],
"type": "string",
"description": "Sets the default scoring weights. Default balanced."
},
"supplier": {
"type": "string"
},
"reference": {
"type": "string"
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted."
},
"analysis_id": {
"type": "string",
"description": "Read a kept analysis (pa_...) instead of making a new one."
},
"invoice_text": {
"type": "string",
"description": "Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below."
},
"source_currency": {
"type": "string",
"description": "ISO code you pay from, e.g. EUR or ZAR."
},
"existing_provider": {
"type": "object",
"description": "Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }."
},
"beneficiary_amount": {
"type": "number",
"description": "What the supplier must receive, in the destination currency (instead of amount)."
},
"destination_country": {
"type": "string",
"description": "ISO 3166 alpha-2 or name, e.g. ZM or Mozambique."
},
"destination_currency": {
"type": "string",
"description": "ISO code the supplier is paid in, e.g. ZMW. Or destination_country."
}
}
}Turn a corporate FX or payment requirement into a PaymentIntent: the currencies, the amount and whether it is what leaves or what must land, the value date, and the principal's own constraints. Accepts a sentence ('pay a Japanese supplier JPY 800m by 15 October') with the source currency, a flat form, or a full intent. The source currency is never assumed. Returns the intent, its hash and every assumption made. Free.
| Argument | Type | Description |
|---|---|---|
| to | string | ISO 4217 code it must land in. |
| from | string | ISO 4217 code the money leaves in. |
| text | string | The requirement in plain words. |
| payer | object | Who is paying, so onboarding_status can be resolved per candidate instead of defaulting to onboardable-with-steps. All optional. |
| amount | number | The amount. |
| value_date | string | ISO date the money must land by. |
| amount_basis | string | Whether the amount leaves (source) or must land (destination). Default destination. |
| max_all_in_bps | number | The principal's own limit on all-in cost against the reference, in basis points. |
| max_settlement_days | number | The principal's own limit on settlement time. |
| allowed_rail_classes | array |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "ISO 4217 code it must land in."
},
"from": {
"type": "string",
"description": "ISO 4217 code the money leaves in."
},
"text": {
"type": "string",
"description": "The requirement in plain words."
},
"payer": {
"type": "object",
"properties": {
"onboarded_providers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Provider ids the payer is already onboarded with (marks that candidate ready)."
},
"registration_country": {
"type": "string",
"description": "ISO 3166 country the paying entity is registered in."
},
"has_local_bank_account": {
"type": "boolean",
"description": "Whether the payer holds a bank account in the destination country."
}
},
"description": "Who is paying, so onboarding_status can be resolved per candidate instead of defaulting to onboardable-with-steps. All optional."
},
"amount": {
"type": "number",
"description": "The amount."
},
"value_date": {
"type": "string",
"description": "ISO date the money must land by."
},
"amount_basis": {
"enum": [
"source",
"destination"
],
"type": "string",
"description": "Whether the amount leaves (source) or must land (destination). Default destination."
},
"max_all_in_bps": {
"type": "number",
"description": "The principal's own limit on all-in cost against the reference, in basis points."
},
"max_settlement_days": {
"type": "number",
"description": "The principal's own limit on settlement time."
},
"allowed_rail_classes": {
"type": "array",
"items": {
"enum": [
"bank",
"specialist_fx",
"payout_network",
"payment_network",
"local_rail",
"stablecoin"
],
"type": "string"
}
}
}
}After your wallet has sent a payment prepared by prepare_payment, give its prepare_id and transaction hash. SwapEazi reads the receipt on chain, verifies it came from the prepared wallet and matches the prepared transaction, and returns a signed payment record for the audit trail. Read-only on chain; moves nothing.
| Argument | Type | Description |
|---|---|---|
| tx_hash* | string | |
| contribute | boolean | True adds one anonymised row (token, network, month, size band) to SwapEazi's cost research. |
| prepare_id* | string |
{
"type": "object",
"required": [
"prepare_id",
"tx_hash"
],
"properties": {
"tx_hash": {
"type": "string"
},
"contribute": {
"type": "boolean",
"description": "True adds one anonymised row (token, network, month, size band) to SwapEazi's cost research."
},
"prepare_id": {
"type": "string"
}
}
}Keyed. Connects the business's OWN account at a rail (yellowcard) for reads and sandbox sending; production sending is off unless the deployment enables it, and the default flow is that the business releases payments itself in its own portal with its API key and secret and a required cap per payment. The credentials are proven with a read (no payment is sent), encrypted at rest and never returned: answers show the key's last four characters and the created date. Prefer POST /api/v1/rail-connections from your own software: credentials passed here travel through the agent's context. SwapEazi holds no funds and has no account in the flow.
| Argument | Type | Description |
|---|---|---|
| env | string | |
| rail* | string | |
| label | string | |
| secret* | string | |
| sender | object | |
| api_key* | string | |
| access_key | string | |
| cap_per_payment* | object |
{
"type": "object",
"required": [
"rail",
"api_key",
"secret",
"cap_per_payment"
],
"properties": {
"env": {
"enum": [
"sandbox",
"production"
],
"type": "string"
},
"rail": {
"enum": [
"yellowcard"
],
"type": "string"
},
"label": {
"type": "string"
},
"secret": {
"type": "string"
},
"sender": {
"type": "object"
},
"api_key": {
"type": "string"
},
"access_key": {
"type": "string"
},
"cap_per_payment": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "number"
},
"currency": {
"type": "string"
}
}
}
}
}Dated corridor news for a currency pair or one currency: provider route launches and exits, licences granted or revoked, central-bank FX and payment rule changes, devaluations, limit changes and outages, collected from payments press and regulator feeds across Africa, Latin America, Asia, the Middle East and Turkey. Each event carries its source link and an evidence label: 'official source' (a regulator or central bank published it), 'announced, unverified' (a company or the press reported it), or 'headline only, not read'. Listed newest first; route launches for the exact pair come back separately as announced_routes, never as payment options. Free.
| Argument | Type | Description |
|---|---|---|
| days | number | Look-back window, 1 to 365. Default 90. |
| kind | string | Optional comma-separated kinds: route_launch, route_exit, licence_granted, licence_revoked, rule_change, devaluation, limit_change, outage, partnership, other. |
| pair | string | Six letters, e.g. NGNCNY. Matches either currency or the exact corridor. |
| limit | number | Events returned, 1 to 100. Default 25. |
| currency | string | One ISO code, e.g. NGN, when no pair is given. |
{
"type": "object",
"properties": {
"days": {
"type": "number",
"description": "Look-back window, 1 to 365. Default 90."
},
"kind": {
"type": "string",
"description": "Optional comma-separated kinds: route_launch, route_exit, licence_granted, licence_revoked, rule_change, devaluation, limit_change, outage, partnership, other."
},
"pair": {
"type": "string",
"description": "Six letters, e.g. NGNCNY. Matches either currency or the exact corridor."
},
"limit": {
"type": "number",
"description": "Events returned, 1 to 100. Default 25."
},
"currency": {
"type": "string",
"description": "One ISO code, e.g. NGN, when no pair is given."
}
}
}How much of the map for a currency pair and size rests on evidence: the coverage tier (evidenced, partial or inferred), how many reconciled outcomes sit behind it, how many candidates carry economics, the reference's publishers, error band and type (hard_peg, derived_peg, fixing_median or home_central_bank), and whether a failure rate is published yet. With country (e.g. CI for XOF), also that country's profile and measured receipts. Free.
| Argument | Type | Description |
|---|---|---|
| to* | string | |
| from* | string | |
| amount | number | |
| country | string | Optional ISO 3166-1 alpha-2 country, e.g. CI for XOF. |
| amount_basis | string |
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"amount": {
"type": "number"
},
"country": {
"type": "string",
"description": "Optional ISO 3166-1 alpha-2 country, e.g. CI for XOF."
},
"amount_basis": {
"enum": [
"source",
"destination"
],
"type": "string"
}
}
}Create a spend mandate for an agent: per-payment cap, period cap, currencies, corridors, rails (bank, provider, stablecoin_wallet), optional cap on cost above the official rate, the person who approves, and an expiry. A router key is required. A person still approves every payment. The mandate does not send money.
| Argument | Type | Description |
|---|---|---|
| period* | string | |
| agent_id* | string | |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
| expires_at* | string | ISO 8601, in the future. |
| rails_allowed* | array | |
| max_per_period* | object | { amount, currency } |
| max_per_payment* | object | { amount, currency } |
| corridors_allowed* | array | e.g. USDT-ZAR |
| approver_person_id* | string | The person who approves. An agent cannot approve alone. |
| currencies_allowed* | array | |
| max_cost_above_official_pct | number | null |
{
"type": "object",
"required": [
"agent_id",
"max_per_payment",
"max_per_period",
"period",
"currencies_allowed",
"corridors_allowed",
"rails_allowed",
"approver_person_id",
"expires_at"
],
"properties": {
"period": {
"enum": [
"day",
"week",
"month"
],
"type": "string"
},
"agent_id": {
"type": "string"
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
},
"expires_at": {
"type": "string",
"description": "ISO 8601, in the future."
},
"rails_allowed": {
"type": "array",
"items": {
"enum": [
"bank",
"provider",
"stablecoin_wallet"
],
"type": "string"
}
},
"max_per_period": {
"type": "object",
"description": "{ amount, currency }"
},
"max_per_payment": {
"type": "object",
"description": "{ amount, currency }"
},
"corridors_allowed": {
"type": "array",
"items": {
"type": "string"
},
"description": "e.g. USDT-ZAR"
},
"approver_person_id": {
"type": "string",
"description": "The person who approves. An agent cannot approve alone."
},
"currencies_allowed": {
"type": "array",
"items": {
"type": "string"
}
},
"max_cost_above_official_pct": {
"type": [
"number",
"null"
]
}
}
}Keyed. A named person approves or rejects a payment intent. The decision is kept with the time, the person and the proposal. An agent cannot approve alone. Nothing is sent.
| Argument | Type | Description |
|---|---|---|
| decision* | string | |
| intent_id* | string | |
| access_key | string | |
| person_name* | string | |
| person_role* | string |
{
"type": "object",
"required": [
"intent_id",
"decision",
"person_name",
"person_role"
],
"properties": {
"decision": {
"enum": [
"approved",
"rejected"
],
"type": "string"
},
"intent_id": {
"type": "string"
},
"access_key": {
"type": "string"
},
"person_name": {
"type": "string"
},
"person_role": {
"type": "string"
}
}
}Call this before initiating any cross-border or cross-currency payment. One call: a payment requirement in, a signed DiscoveryReport (a Decision Brief) out, across bank, PSP and stablecoin rails side by side — each leg's cost in basis points against an independent reference, settlement time, licence and evidence class. Pass a needed_by date to also get timing_scenarios (fund now, lock a forward, convert and park, or hold unhedged — the router's own due-date scenarios, unordered), fx_exposure (what funding the obligation today would cost at +1/+3/+5% adverse moves, arithmetic on the reference, not a forecast), and hedge_scenarios (no/half/full hedge, indicative cost from covered interest parity, residual exposure — scenario presentation only, never a recommended ratio or automated hedge). historical_context today is band-wide for the pair and size, not yet specific to the caller; current_quote, if passed, is measured against the reference the same way (the Markup Measure). what_we_dont_know is always present, even when empty. Nothing here ranks, picks or recommends. Does not execute, hold or price money. Free within the daily allowance; a key lifts it. The options/cost path is typically under 3 seconds, cached metadata only; with needed_by, timing_scenarios adds one live routing lookup and can take longer. Returns a compact view by default (one short object per option; what_we_dont_know, regulatory_notes and the scenarios in full) that points at the signed Options Map behind it; pass detail: "full" for the whole report.
| Argument | Type | Description |
|---|---|---|
| payer | object | |
| amount* | number | The amount, greater than zero. |
| client | object | |
| detail | string | compact (default): a short summary that points at the signed full document, sized for a tool result. full: the whole document, which can exceed 100 KB. |
| amount_in | string | Which currency amount is stated in. Overrides direction's default, e.g. paying a fixed destination amount while funding from the source currency. |
| direction | string | pay (default): amount is what leaves. receive: amount is what must land. |
| needed_by | string | Optional ISO date the money must land by. Adds timing_scenarios, fx_exposure and hedge_scenarios to the report, and each option's settlement.release_by: the latest release that lands by this date at the rail's later and earlier typical settle_days (on bank rails, the provider's cut-off on a banking day; the cut-off is not on record). |
| release_at | string | Optional ISO date-time the payment will be released; default now. Each option's settlement.release_window states whether its rail moves at that moment (bank rails on banking days only, stablecoin rails around the clock), when it starts moving, the landing dates that follow, any sourced time-based markup, and what is not on record (cut-offs, bank holidays). |
| constraints | object | |
| current_quote | object | Optional: a quote already held, measured as given against the reference. |
| rails_allowed | array | Default: all. Only bank and stablecoin filter directly today; psp/dex leave every non-excluded rail in. |
| source_currency* | string | ISO 4217 code the payment leaves in, e.g. 'EUR'. |
| target_currency* | string | ISO 4217 code the payment must land in, e.g. 'ZAR'. |
{
"type": "object",
"required": [
"amount",
"source_currency",
"target_currency"
],
"properties": {
"payer": {
"type": "object",
"properties": {
"entity_type": {
"enum": [
"corporate",
"sme",
"fintech",
"crypto_native",
"individual"
],
"type": "string"
},
"jurisdiction": {
"type": "string",
"description": "Optional ISO 3166-1 alpha-2 country of the payer."
}
}
},
"amount": {
"type": "number",
"description": "The amount, greater than zero.",
"exclusiveMinimum": 0
},
"client": {
"type": "object",
"properties": {
"type": {
"enum": [
"agent",
"human"
],
"type": "string"
},
"agent_id": {
"type": "string",
"description": "Optional, self-declared; logged."
}
}
},
"detail": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "compact (default): a short summary that points at the signed full document, sized for a tool result. full: the whole document, which can exceed 100 KB."
},
"amount_in": {
"enum": [
"source",
"destination"
],
"type": "string",
"description": "Which currency amount is stated in. Overrides direction's default, e.g. paying a fixed destination amount while funding from the source currency."
},
"direction": {
"enum": [
"pay",
"receive"
],
"type": "string",
"description": "pay (default): amount is what leaves. receive: amount is what must land."
},
"needed_by": {
"type": "string",
"description": "Optional ISO date the money must land by. Adds timing_scenarios, fx_exposure and hedge_scenarios to the report, and each option's settlement.release_by: the latest release that lands by this date at the rail's later and earlier typical settle_days (on bank rails, the provider's cut-off on a banking day; the cut-off is not on record)."
},
"release_at": {
"type": "string",
"description": "Optional ISO date-time the payment will be released; default now. Each option's settlement.release_window states whether its rail moves at that moment (bank rails on banking days only, stablecoin rails around the clock), when it starts moving, the landing dates that follow, any sourced time-based markup, and what is not on record (cut-offs, bank holidays)."
},
"constraints": {
"type": "object",
"properties": {
"exclude_providers": {
"type": "array",
"items": {
"type": "string"
}
},
"require_licensed_in": {
"type": "array",
"items": {
"type": "string"
},
"description": "Not yet filterable; listed in what_we_dont_know when given."
},
"max_settlement_hours": {
"type": "number"
}
}
},
"current_quote": {
"type": "object",
"required": [
"rate"
],
"properties": {
"fees": {
"type": "number",
"description": "Optional, in the source currency."
},
"rate": {
"type": "number",
"description": "Destination units per source unit.",
"exclusiveMinimum": 0
},
"provider": {
"type": "string"
},
"quoted_at": {
"type": "string"
}
},
"description": "Optional: a quote already held, measured as given against the reference."
},
"rails_allowed": {
"type": "array",
"items": {
"enum": [
"bank",
"psp",
"stablecoin",
"dex"
],
"type": "string"
},
"description": "Default: all. Only bank and stablecoin filter directly today; psp/dex leave every non-excluded rail in."
},
"source_currency": {
"type": "string",
"description": "ISO 4217 code the payment leaves in, e.g. 'EUR'."
},
"target_currency": {
"type": "string",
"description": "ISO 4217 code the payment must land in, e.g. 'ZAR'."
}
}
}Read a payment case by intent_id (pi_…): its lifecycle status and who reported it, the Evidence Passport (intent, evidence with provenance and freshness, provider access and dependencies, decision, outcome), unknowns, exceptions with owner and next action, and the timeline. Use it before acting on a payment, to see what is current, what has expired and what must happen next. Read-only: it changes nothing and moves no money. Cases opened with an organisation's key need that key.
| Argument | Type | Description |
|---|---|---|
| intent_id* | string | pi_… from POST /api/v1/cases. |
{
"type": "object",
"required": [
"intent_id"
],
"properties": {
"intent_id": {
"type": "string",
"description": "pi_… from POST /api/v1/cases."
}
}
}Spec v1.0 name for assess_route: the official rate for the pair and each route's all-in cost and FX figure with source, read time, freshness and evidence type, settlement and requirements, under an assessment_id. Same arguments as assess_route.
| Argument | Type | Description |
|---|---|---|
| to | string | |
| from | string | |
| amount | number | Amount leaving, in the source currency. |
| corridor | string | e.g. EUR-ZMW instead of from and to. |
| access_key | string |
{
"type": "object",
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"amount": {
"type": "number",
"description": "Amount leaving, in the source currency."
},
"corridor": {
"type": "string",
"description": "e.g. EUR-ZMW instead of from and to."
},
"access_key": {
"type": "string"
}
}
}List corridors and each route's standing: proven (a real price and at least one closed landing), priced_only, or no_live_route with a reason. Includes last_priced_at, last_landed_at, landed_count and max_age_seconds. A route is never proven without a closed landing. Free callers see masked route names. Same records as GET /api/v1/coverage?view=routes.
| Argument | Type | Description |
|---|---|---|
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
{
"type": "object",
"properties": {
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
}
}
}Read a mandate by id (man_...) for the organisation of the router key. A router key is required.
| Argument | Type | Description |
|---|---|---|
| id | string | man_... |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
| mandate_id | string | Same as id. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "man_..."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
},
"mandate_id": {
"type": "string",
"description": "Same as id."
}
}
}Return a stored Rate Receipt by id (rr_...). Schema swapeazi.rate_receipt.v1. Includes max_age_seconds. Free callers see a masked publisher; a router key sees the source name.
| Argument | Type | Description |
|---|---|---|
| id* | string | rr_... from price_routes. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "rr_... from price_routes."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
}
}
}A payment intent SwapEazi is watching (from route_intent with remember: true): today's route and what paying now, locking the rate and holding unhedged need, every day since it was kept, and what changed (the selected route, the cost of paying today, the payer's lock-at level, the due date). Signed. Facts only; SwapEazi moves no money.
| Argument | Type | Description |
|---|---|---|
| intent_id* | string |
{
"type": "object",
"required": [
"intent_id"
],
"properties": {
"intent_id": {
"type": "string"
}
}
}Keyed. A business, a rail or an agent joins. A rail may attach a quote feed as an API key or an OAuth-style connection and one published rate. No placement is sold. SwapEazi does not hold or move money.
| Argument | Type | Description |
|---|---|---|
| to | string | |
| from | string | |
| name* | string | |
| rate | number | |
| party* | string | |
| contact* | string | |
| rail_kind | string | |
| access_key | string | |
| quote_feed | string |
{
"type": "object",
"required": [
"party",
"name",
"contact"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"name": {
"type": "string"
},
"rate": {
"type": "number"
},
"party": {
"enum": [
"business",
"rail",
"agent"
],
"type": "string"
},
"contact": {
"type": "string"
},
"rail_kind": {
"type": "string"
},
"access_key": {
"type": "string"
},
"quote_feed": {
"enum": [
"api_key",
"oauth"
],
"type": "string"
}
}
}For a currency pair (e.g. ZAR-USD, NGN-USD, KES-USD, USD-MWK) and a ticket size: each venue type (exchange order books, stablecoin pools, P2P adverts, ramps and off-ramps, OTC desks, banks) with whether the evidence read shows depth at that size, the measured slippage and landing cost at that size with a Rate Receipt, the largest size the evidence supports, or Being measured with the reason. With prefunding (amount held, days held), idle fiat prefunding and stablecoin reserves on the same evidence: cost to enter and exit at that size, the peg and exit depth from the stablecoin profiles, and the past official-rate move over the same days. Figures, not advice. Unknowns listed. SwapEazi never holds, creates or moves liquidity. Free callers see Route A, Route B; a router key shows venue names. Same as GET/POST /api/v1/liquidity.
| Argument | Type | Description |
|---|---|---|
| to | string | |
| from | string | |
| pair | string | e.g. ZAR-USD or USD-MWK. Or from and to. |
| amount* | number | Ticket size, in the from currency unless amount_currency says otherwise. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
| prefunding | object | { amount, currency?, corridor?, days_held }: an amount held to prefund the corridor, and for how many days (1 to 365). |
| amount_currency | string | The from or the to currency. Default from. |
{
"type": "object",
"required": [
"amount"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"pair": {
"type": "string",
"description": "e.g. ZAR-USD or USD-MWK. Or from and to."
},
"amount": {
"type": "number",
"description": "Ticket size, in the from currency unless amount_currency says otherwise."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
},
"prefunding": {
"type": "object",
"description": "{ amount, currency?, corridor?, days_held }: an amount held to prefund the corridor, and for how many days (1 to 365)."
},
"amount_currency": {
"type": "string",
"description": "The from or the to currency. Default from."
}
}
}Keyed. The rail accounts connected with this router key: rail, env, label, the API key's last four characters, created date and cap per payment. Never a key or a secret.
| Argument | Type | Description |
|---|---|---|
| access_key | string |
{
"type": "object",
"properties": {
"access_key": {
"type": "string"
}
}
}The signed Options Map for a PaymentIntent: every rail and provider the graph holds for the pair and size, each with its access facts, documented capacity, settlement window, economics basis (observed, band or unpublished) and evidence class, and whether it sits inside, outside or unknown against the principal's constraints. Each candidate also carries route_family (bank_correspondent or stablecoin_casp), regulatory_risk (stable, watch, restricted or blocked, tied to a tracked rule) and onboarding_status (ready, onboardable, ineligible or unknown, with onboarding_gap naming what's missing) so an agent can filter out ineligible or blocked routes before quoting. route_families lists every family even one with zero candidates, reason no_eligible_provider, rather than hiding it. Sorted by coverage tier, rail class and name, never by a rank. payout_rules lists the rules that reach the payout per route (applies or depends, each with its document; document_not_read when found by search). A guide, not advice. Pass an intent (any form compile_intent takes, including payer) or an intent_id. Free within the daily allowance; a key lifts it. Returns a compact view by default (one short object per candidate, every unknown in full) that points at the signed full map; pass detail: "full" for the whole signed document, or map_id to read back a map made earlier.
| Argument | Type | Description |
|---|---|---|
| detail | string | compact (default): a short summary that points at the signed full document, sized for a tool result. full: the whole document, which can exceed 100 KB. |
| intent | object | A PaymentIntent, a flat form or { text, from }. |
| map_id | string | A map_id from an earlier map_options call: returns that stored, signed map (with expired) instead of making a new one. |
| country | string | Optional ISO 3166-1 alpha-2 country of the payer (or payee) for a multi-country currency, e.g. CI for XOF: attaches that country's profile (banks, fees, payment-side rules, each with source and confidence) and the receipts measured there. |
| intent_id | string | An intent compiled earlier. |
| release_at | string | Optional ISO date-time the payment will be released; default now. Sets each candidate's settlement.release_window. |
{
"type": "object",
"properties": {
"detail": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "compact (default): a short summary that points at the signed full document, sized for a tool result. full: the whole document, which can exceed 100 KB."
},
"intent": {
"type": "object",
"description": "A PaymentIntent, a flat form or { text, from }."
},
"map_id": {
"type": "string",
"description": "A map_id from an earlier map_options call: returns that stored, signed map (with expired) instead of making a new one."
},
"country": {
"type": "string",
"description": "Optional ISO 3166-1 alpha-2 country of the payer (or payee) for a multi-country currency, e.g. CI for XOF: attaches that country's profile (banks, fees, payment-side rules, each with source and confidence) and the receipts measured there."
},
"intent_id": {
"type": "string",
"description": "An intent compiled earlier."
},
"release_at": {
"type": "string",
"description": "Optional ISO date-time the payment will be released; default now. Sets each candidate's settlement.release_window."
}
}
}Where dollars are on-chain at your size: for USDC and USDT (and ZARP, cNGN as to_asset), executable depth and cost at the amount on Ethereum, Tron, Solana, Base, BNB Chain, Arbitrum and Polygon, from keyless DEX aggregator quotes (KyberSwap, ParaSwap, Jupiter): price impact against a USD 100 quote, cost against par with gas and stated fees, and each network's published time to finality. Bridge cost and time between chains from Across, Circle CCTP and LI.FI. The hourly reads at USD 10k, 100k, 1m and 5m for the pair, each with its age. With destination (two-letter country), the documented facts on whether suppliers there take stablecoins directly (not established where we hold no source) and the off-ramp venues SwapEazi reads in its currency. Every figure has its source, time and a Rate Receipt; each failure keeps its reason. Figures, not advice; never ranked. SwapEazi never holds or moves money and never asks for a wallet signature. Same as GET/POST /api/v1/onchain-liquidity. Free within the daily allowance.
| Argument | Type | Description |
|---|---|---|
| amount* | number | The ticket in US dollars (dollar stablecoins at par). |
| chains | array | Any of ethereum, tron, solana, base, bsc, arbitrum, polygon. Default all. |
| to_asset | string | USDC, USDT, ZARP or cNGN (ZAR and NGN map to ZARP and cNGN). Default: the other dollar coin. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header: shows exchange and P2P venue names in the destination block. |
| from_asset | string | USDC or USDT. Default USDC. |
| destination | string | Optional supplier country, two letters (e.g. HK, CN, AE, NG, ZA, KE). |
{
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "The ticket in US dollars (dollar stablecoins at par)."
},
"chains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Any of ethereum, tron, solana, base, bsc, arbitrum, polygon. Default all."
},
"to_asset": {
"type": "string",
"description": "USDC, USDT, ZARP or cNGN (ZAR and NGN map to ZARP and cNGN). Default: the other dollar coin."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header: shows exchange and P2P venue names in the destination block."
},
"from_asset": {
"type": "string",
"description": "USDC or USDT. Default USDC."
},
"destination": {
"type": "string",
"description": "Optional supplier country, two letters (e.g. HK, CN, AE, NG, ZA, KE)."
}
}
}A dated series per currency of the gap between a public-advert median and the official rate. Labelled market-observed, never an official rate. Currencies: ZAR, MZN, MWK, ZMW, NGN, KES, BRL, ARS, PHP. Too few adverts, or no read on record, is null with a reason. A missing gap is never zero. Free.
| Argument | Type | Description |
|---|---|---|
| date | string | YYYY-MM-DD. Default today (UTC). |
{
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD. Default today (UTC)."
}
}
}Read the controls that govern the payments an agent prepares for an organisation: its spend profiles with today's and this month's spend against each budget, the payments waiting for a person to approve (with any transaction already prepared after approval), and the audit trail of prepared and confirmed payments. With approval_id, reads that one approval. Read-only. Needs the organisation's key.
| Argument | Type | Description |
|---|---|---|
| approval_id | string | rapr_… returned by prepare_payment when a person must approve. |
{
"type": "object",
"properties": {
"approval_id": {
"type": "string",
"description": "rapr_… returned by prepare_payment when a person must approve."
}
}
}Keyed. A business states the payee, the corridor, the amount the payee must receive, and the deadline. Returns a proposal: bank, OTC, ramp, AMM and secure P2P wallet routes, including the business's own negotiated rate when one is on record. The selected route is the lower total the payer sends to land the full amount by the deadline. Each figure is measured, a public quote read at a date and not locked, or Being measured. SwapEazi does not hold or move money. A person still approves.
| Argument | Type | Description |
|---|---|---|
| to* | string | |
| from* | string | |
| deadline* | string | YYYY-MM-DD |
| access_key | string | |
| payee_name* | string | |
| customer_id | string | |
| amount_receive* | number |
{
"type": "object",
"required": [
"payee_name",
"from",
"to",
"amount_receive",
"deadline"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"deadline": {
"type": "string",
"description": "YYYY-MM-DD"
},
"access_key": {
"type": "string"
},
"payee_name": {
"type": "string"
},
"customer_id": {
"type": "string"
},
"amount_receive": {
"type": "number"
}
}
}Read a payment run by run_id: each payment's status (prepared, needs_attention with reasons, no_evidence), its assessment and Rate Receipts, approval, release record and what landed. export: true returns the audit export, where any payment without an assessment, approval or release record shows "no evidence". pr_sample needs no key; a real run needs the router key that made it.
| Argument | Type | Description |
|---|---|---|
| export | boolean | true: the audit export (JSON) instead of the run. |
| run_id* | string | pr_... from run_payments, or pr_sample. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
{
"type": "object",
"required": [
"run_id"
],
"properties": {
"export": {
"type": "boolean",
"description": "true: the audit export (JSON) instead of the run."
},
"run_id": {
"type": "string",
"description": "pr_... from run_payments, or pr_sample."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
}
}
}Pre-release check on a whole payout file before it goes to the company's own bank or PSP. Send the file's text: an ISO 20022 pain.001 credit-transfer file (versions .03 to .12) or a CSV with a header row (comma or semicolon, Dutch or English column names). Every row comes back ok, needs_person or blocked, with the reasons: missing name or account, failed IBAN checksum, a BIC from a different country than the IBAN, SA branch code, SADC mobile money, too many decimals, a euro payment outside SEPA, an execution date in the past or on a weekend, possible duplicates, and rows above the company's own review limit. With a signing key set, it also returns a signed record of the check (file hash and each row's state, no names or accounts). SwapEazi never sends, holds or routes the money: the company releases the file itself. Paid: configure this server with an Authorization Bearer key (https://swapeazi.io/pricing).
| Argument | Type | Description |
|---|---|---|
| file* | string | The payout file's text: pain.001 XML or a CSV with a header row. |
| today | string | Release date, YYYY-MM-DD. Defaults to today (UTC). |
| review_above | number | Rows above this amount need a person, whatever else they pass. The company's own limit. |
{
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"description": "The payout file's text: pain.001 XML or a CSV with a header row."
},
"today": {
"type": "string",
"description": "Release date, YYYY-MM-DD. Defaults to today (UTC)."
},
"review_above": {
"type": "number",
"description": "Rows above this amount need a person, whatever else they pass. The company's own limit."
}
}
}Which payout rules reach a payout, and when: for a corridor (two-letter countries, or currencies) and a route (bank or stablecoin), each rule SwapEazi holds answers applies, depends (and on what) or does not apply, with its dated steps, its official document and the day it was read. Drafts are never answered as law. Information from each rule's own document, not legal advice. route_intent carries the rules that reach its payout in its rules field. Read-only, free, no key.
| Argument | Type | Description |
|---|---|---|
| to* | string | Paying to: a two-letter country (ZW) or a currency (USD). |
| from* | string | Paying from: a two-letter country (ZA) or a currency (ZAR). |
| route | string | How the payout goes; both when left out. |
| currency | string | Currency sent, when from and to are countries. |
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "Paying to: a two-letter country (ZW) or a currency (USD)."
},
"from": {
"type": "string",
"description": "Paying from: a two-letter country (ZA) or a currency (ZAR)."
},
"route": {
"enum": [
"bank",
"stablecoin"
],
"type": "string",
"description": "How the payout goes; both when left out."
},
"currency": {
"type": "string",
"description": "Currency sent, when from and to are countries."
}
}
}Prepare an unsigned USDC or USDT transaction for the paying wallet you control, on Base, Arbitrum, Optimism, Polygon or BNB Chain, or USDT (TRC-20) on Tron (chain_id 728126428, T... addresses; TronLink signs it). SwapEazi screens the recipient's address and verifies the organisation's spend profile first: the cap per payment, the daily and monthly budget, approved recipients and chains, and the approval line. A person approves every payment an agent prepares: within the rules it returns an approval_id, the approver decides at /approvals, and once approved payment_controls with that approval_id returns the transaction (a plain transfer, or a swap or bridge with no SwapEazi fee) for your wallet to sign; outside the rules it explains why. Pass the map_id and candidate_id of the stablecoin option you took from discover_payment or map_options, so the approver sees what the guide showed for it and the records name the map; the guide never picks it. SwapEazi never signs, holds keys or moves funds. With private: true, the payment runs through NEAR Intents' confidential mode under the same rules; that is also the way between Tron and an EVM chain. With profile_id, needs the organisation's key.
| Argument | Type | Description |
|---|---|---|
| to* | string | The recipient's address on the chain it receives on (0x, or T... on Tron), or your own deposit address at an off-ramp. |
| from* | string | The paying wallet's address: 0x on EVM chains, T... (base58check) on Tron. |
| rules | object | Inline rules when no profile is used: max_per_payment_usd, approval_above_usd, daily_limit_usd, monthly_limit_usd, allowed_recipients, allowed_chains. |
| token* | string | |
| amount* | number | |
| map_id | string | The map_id from discover_payment or map_options. The map must not have expired. |
| private | boolean | Pay privately through NEAR Intents' confidential mode: one transfer to a deposit address for your wallet to sign; settles in full or refunds to your wallet. The quote's signature and correlation id go into the signed record. Read progress with private_payment_status. |
| chain_id* | number | 8453 Base, 42161 Arbitrum, 10 Optimism, 137 Polygon, 56 BNB Chain, 728126428 Tron (USDT only). |
| to_token | string | |
| profile_id | string | prof_… from payment_controls; applies the organisation's budgets and approval line. |
| to_chain_id | number | The chain the recipient receives on, when it differs from chain_id. To or from Tron (728126428) needs private: true. |
| candidate_id | string | The stablecoin candidate in that map this payment takes. Bank candidates are sent by your bank or provider, not prepared here. |
| destination_currency | string | The local currency the money is for, so local stablecoin rules are assessed, e.g. ZAR. |
{
"type": "object",
"required": [
"token",
"chain_id",
"from",
"to",
"amount"
],
"properties": {
"to": {
"type": "string",
"description": "The recipient's address on the chain it receives on (0x, or T... on Tron), or your own deposit address at an off-ramp."
},
"from": {
"type": "string",
"description": "The paying wallet's address: 0x on EVM chains, T... (base58check) on Tron."
},
"rules": {
"type": "object",
"description": "Inline rules when no profile is used: max_per_payment_usd, approval_above_usd, daily_limit_usd, monthly_limit_usd, allowed_recipients, allowed_chains."
},
"token": {
"enum": [
"USDC",
"USDT"
],
"type": "string"
},
"amount": {
"type": "number"
},
"map_id": {
"type": "string",
"description": "The map_id from discover_payment or map_options. The map must not have expired."
},
"private": {
"type": "boolean",
"description": "Pay privately through NEAR Intents' confidential mode: one transfer to a deposit address for your wallet to sign; settles in full or refunds to your wallet. The quote's signature and correlation id go into the signed record. Read progress with private_payment_status."
},
"chain_id": {
"type": "number",
"description": "8453 Base, 42161 Arbitrum, 10 Optimism, 137 Polygon, 56 BNB Chain, 728126428 Tron (USDT only)."
},
"to_token": {
"enum": [
"USDC",
"USDT"
],
"type": "string"
},
"profile_id": {
"type": "string",
"description": "prof_… from payment_controls; applies the organisation's budgets and approval line."
},
"to_chain_id": {
"type": "number",
"description": "The chain the recipient receives on, when it differs from chain_id. To or from Tron (728126428) needs private: true."
},
"candidate_id": {
"type": "string",
"description": "The stablecoin candidate in that map this payment takes. Bank candidates are sent by your bank or provider, not prepared here."
},
"destination_currency": {
"type": "string",
"description": "The local currency the money is for, so local stablecoin rules are assessed, e.g. ZAR."
}
}
}Spec v1.0 name for run_payments: prepares each payment (payee validation, route assessment, instruction, approval digest) and returns each payment's lifecycle state. Never approves or sends. Same arguments as run_payments; sample: true for the synthetic run.
| Argument | Type | Description |
|---|---|---|
| file | string | |
| sample | boolean | |
| payables | array | |
| access_key | string | |
| source_currency | string |
{
"type": "object",
"properties": {
"file": {
"type": "string"
},
"sample": {
"type": "boolean"
},
"payables": {
"type": "array",
"items": {
"type": "object"
}
},
"access_key": {
"type": "string"
},
"source_currency": {
"type": "string"
}
}
}Read public prices for a corridor at a payment size: on-chain pools, public order books and public adverts, with no partner key. Each figure is a route option with a Rate Receipt (schema swapeazi.rate_receipt.v1): publisher, source_type, read_at, size_priced, rate, official_rate, cost_pct, confidence, evidence_ref and status (proven, priced_only or no_live_route). max_age_seconds says when to read again. A missing figure is null with a reason. Free callers see Route A, Route B; a router key sees source names. Never executes.
| Argument | Type | Description |
|---|---|---|
| to | string | Destination currency, e.g. ZAR. |
| from | string | Source currency, e.g. USDT. |
| amount | number | Amount in the source currency. Default 10000. |
| corridor | string | Instead of from and to: USDT-ZAR. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "Destination currency, e.g. ZAR."
},
"from": {
"type": "string",
"description": "Source currency, e.g. USDT."
},
"amount": {
"type": "number",
"description": "Amount in the source currency. Default 10000."
},
"corridor": {
"type": "string",
"description": "Instead of from and to: USDT-ZAR."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
}
}
}For a payment prepared with private: true, give the deposit_address from its quote_proof. Returns the NEAR Intents status: PENDING_DEPOSIT, KNOWN_DEPOSIT_TX, PROCESSING, SUCCESS, REFUNDED, INCOMPLETE_DEPOSIT or FAILED, with the reason when it cannot be read. Read-only, free, no key.
| Argument | Type | Description |
|---|---|---|
| deposit_address* | string |
{
"type": "object",
"required": [
"deposit_address"
],
"properties": {
"deposit_address": {
"type": "string"
}
}
}Keyed. With intent_id: after a person has approved, the approved instruction for your rail, with a Rate Receipt of the rate against the official rate and the negotiated deal; where no live connection is configured the adapter is marked stub. The default is that the business releases the payment itself in its own bank or rail portal (release_in_own_bank on the approved payment); SwapEazi never sends it. Sandbox only: with run_id, payment_id and connection_id, sends ONE Payment Run payment a named person approved through the business's OWN connected rail account (Yellow Card sandbox; production stays off unless the deployment sets YELLOWCARD_ENV=production), with the rail's own idempotency key, and returns the submission with a Rate Receipt and the release record. Refused, with the reason, without a recorded approval, when the payment changed since approval, above the connection's cap, or for an account other than the one approved. With run_id and payment_id only: reads that payment's status from the rail. SwapEazi holds no funds and has no account in the flow.
| Argument | Type | Description |
|---|---|---|
| reason | string | |
| run_id | string | |
| intent_id | string | |
| access_key | string | |
| channel_id | string | |
| network_id | string | |
| payment_id | string | |
| account_type | string | |
| connection_id | string | |
| account_number | string | The payee's full account number as approved; SwapEazi keeps only its last four characters and matches this against the approved instruction. |
{
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"run_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"access_key": {
"type": "string"
},
"channel_id": {
"type": "string"
},
"network_id": {
"type": "string"
},
"payment_id": {
"type": "string"
},
"account_type": {
"enum": [
"bank",
"momo"
],
"type": "string"
},
"connection_id": {
"type": "string"
},
"account_number": {
"type": "string",
"description": "The payee's full account number as approved; SwapEazi keeps only its last four characters and matches this against the approved instruction."
}
}
}Keyed. For one corridor, the rail's own published rate beside the official rate and a public market read when one exists. Position is lower_landed_cost, higher_landed_cost or unknown. A missing figure is Being measured.
| Argument | Type | Description |
|---|---|---|
| to* | string | |
| from* | string | |
| access_key | string |
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"access_key": {
"type": "string"
}
}
}Keyed. Returns the dated history of comparisons for one customer and corridor: the rate on each prepared or reconciled payment against that day's official rate, the negotiated deal (margin in bps or a fixed spread, with the customer's own bank label), and a public market price when one was read. Drift is in bps and in the sent currency. above_negotiated is set when the gap over the deal exceeds the stored tolerance. A missing figure is null. The payment stays with the customer's own bank. A router key is required.
| Argument | Type | Description |
|---|---|---|
| to* | string | |
| from* | string | |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
| customer_id* | string |
{
"type": "object",
"required": [
"customer_id",
"from",
"to"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
},
"customer_id": {
"type": "string"
}
}
}Hard eligibility first (complete cost, not stale, settles by the due date, licence active, not excluded by route health), then configurable scoring (total cost, speed, reliability, liquidity, compliance), and the recommendation with why, alternatives, data used, missing information and freshness; or no reliable recommendation with the reasons. Not a firm quote: confirm with the provider before approval. One analysis (POST /api/v1/payment-analyses), the same service for every payment-intelligence tool. Every figure labelled LIVE, INDICATIVE, HISTORICAL or ESTIMATED; estimated savings are never realised. Free: shares the route-assessment allowance.
| Argument | Type | Description |
|---|---|---|
| amount | number | Amount, in currency (default the source currency). |
| weights | object | Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1. |
| currency | string | The currency of amount: the source currency, or the destination one (then it is what the supplier receives). |
| due_date | string | YYYY-MM-DD: a route that cannot settle by then is not eligible. |
| priority | string | Sets the default scoring weights. Default balanced. |
| supplier | string | |
| reference | string | |
| access_key | string | A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted. |
| analysis_id | string | Read a kept analysis (pa_...) instead of making a new one. |
| invoice_text | string | Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below. |
| source_currency | string | ISO code you pay from, e.g. EUR or ZAR. |
| existing_provider | object | Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }. |
| beneficiary_amount | number | What the supplier must receive, in the destination currency (instead of amount). |
| destination_country | string | ISO 3166 alpha-2 or name, e.g. ZM or Mozambique. |
| destination_currency | string | ISO code the supplier is paid in, e.g. ZMW. Or destination_country. |
{
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount, in currency (default the source currency)."
},
"weights": {
"type": "object",
"description": "Your own scoring weights: { total_cost, speed, reliability, liquidity, compliance }, non-negative, normalised to 1."
},
"currency": {
"type": "string",
"description": "The currency of amount: the source currency, or the destination one (then it is what the supplier receives)."
},
"due_date": {
"type": "string",
"description": "YYYY-MM-DD: a route that cannot settle by then is not eligible."
},
"priority": {
"enum": [
"cost",
"speed",
"balanced"
],
"type": "string",
"description": "Sets the default scoring weights. Default balanced."
},
"supplier": {
"type": "string"
},
"reference": {
"type": "string"
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header: names the routes and is not counted."
},
"analysis_id": {
"type": "string",
"description": "Read a kept analysis (pa_...) instead of making a new one."
},
"invoice_text": {
"type": "string",
"description": "Paste the invoice or a sentence (e.g. 'Invoice INV-2207, Lusaka Copper Supplies Ltd, Zambia. Amount due: EUR 80,000. Due 2026-11-20'). Or the fields below."
},
"source_currency": {
"type": "string",
"description": "ISO code you pay from, e.g. EUR or ZAR."
},
"existing_provider": {
"type": "object",
"description": "Your current provider: { provider, kind: quote | entered_rate | past_payment, rate (destination per source unit) or landed_amount, fees: { transaction, intermediary, payout } in the source currency, fees_deducted_destination, quoted_at, valid_until }."
},
"beneficiary_amount": {
"type": "number",
"description": "What the supplier must receive, in the destination currency (instead of amount)."
},
"destination_country": {
"type": "string",
"description": "ISO 3166 alpha-2 or name, e.g. ZM or Mozambique."
},
"destination_currency": {
"type": "string",
"description": "ISO code the supplier is paid in, e.g. ZMW. Or destination_country."
}
}
}After the money moved: post what was sent and what landed (or the all-in cost) against the map it was chosen from. Returns the expected band beside the realised cost, signed. The outcome is kept by pair and size band only and later maps at that size carry it, so bands tighten and unknowns close. Economics only. Free.
| Argument | Type | Description |
|---|---|---|
| map_id* | string | |
| source | string | |
| realised* | object | |
| proof_ref | string | Your own reference for the proof; never an account number. |
| candidate_id_used* | string | The candidate_id from the map the payment went through. |
{
"type": "object",
"required": [
"map_id",
"candidate_id_used",
"realised"
],
"properties": {
"map_id": {
"type": "string"
},
"source": {
"enum": [
"bank_mt",
"swift",
"onchain_tx",
"manual_upload"
],
"type": "string"
},
"realised": {
"type": "object",
"properties": {
"failure": {
"type": "boolean"
},
"settled_at": {
"type": "string"
},
"sent_amount": {
"type": "number"
},
"landed_amount": {
"type": "number"
},
"all_in_bps_vs_ref": {
"type": "number"
}
}
},
"proof_ref": {
"type": "string",
"description": "Your own reference for the proof; never an account number."
},
"candidate_id_used": {
"type": "string",
"description": "The candidate_id from the map the payment went through."
}
}
}Record what landed for released payments in a run: amount sent, amount landed, settlement time, proof reference, the official rate with a Rate Receipt, realised all-in cost in percent and in the sent currency, and position inside, above or below the assessment range. The same proof reference is rejected the second time. dry_run: true validates and writes nothing. A payment with no assessment is flagged no_evidence. A router key is required except for pr_sample. Never sends money.
| Argument | Type | Description |
|---|---|---|
| run_id* | string | pr_... or pr_sample. |
| dry_run | boolean | true: validate only, write nothing. |
| payments* | array | [{ payment_id, sent_amount, landed_amount, settled_at?, proof_ref, source? }]. proof_ref is an MT103 reference, a transaction hash or a provider reference. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
{
"type": "object",
"required": [
"run_id",
"payments"
],
"properties": {
"run_id": {
"type": "string",
"description": "pr_... or pr_sample."
},
"dry_run": {
"type": "boolean",
"description": "true: validate only, write nothing."
},
"payments": {
"type": "array",
"items": {
"type": "object"
},
"description": "[{ payment_id, sent_amount, landed_amount, settled_at?, proof_ref, source? }]. proof_ref is an MT103 reference, a transaction hash or a provider reference."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
}
}
}Close a remembered intent once the money arrived: what left (source currency) and what arrived (destination currency), and/or attach a stablecoin leg by chain and transaction hash, verified from the chain. SwapEazi measures it against the independent reference and against what was routed, and every later route on the pair carries it as a measured payment. On a recurring intent it closes the current cycle only and the series moves to its next due date. Amounts only, never names or account numbers.
| Argument | Type | Description |
|---|---|---|
| tx | string | For a stablecoin leg: the transaction hash; read and priced from the chain and added to the payment record. |
| sent | number | |
| chain | string | For a stablecoin leg: base, ethereum, arbitrum, optimism, polygon or celo. |
| landed | number | |
| provider | string | Defaults to the route selected on the last day. |
| intent_id* | string | |
| settled_at | string | YYYY-MM-DD |
{
"type": "object",
"required": [
"intent_id"
],
"properties": {
"tx": {
"type": "string",
"description": "For a stablecoin leg: the transaction hash; read and priced from the chain and added to the payment record."
},
"sent": {
"type": "number"
},
"chain": {
"type": "string",
"description": "For a stablecoin leg: base, ethereum, arbitrum, optimism, polygon or celo."
},
"landed": {
"type": "number"
},
"provider": {
"type": "string",
"description": "Defaults to the route selected on the last day."
},
"intent_id": {
"type": "string"
},
"settled_at": {
"type": "string",
"description": "YYYY-MM-DD"
}
}
}At the moment a material payment is released, record it against the organisation's release policy: the map_id and measure_id on file, who released it, and any exception with its reason and approver. When an agent releases under a policy with agent_autonomy tiers, the record states the tier its amount falls in and the agent_approval on record for it. Returns a Release Evidence Record, appended to the organisation's hash chain and signed. It records; it never blocks, executes or moves money. A release with no map is still recorded, flagged as a policy miss. Needs the organisation's key.
| Argument | Type | Description |
|---|---|---|
| uetr | string | The payment's SWIFT UETR (UUID v4), optional: ties the record to the payment itself. |
| amount | object | |
| map_id | string | |
| exception | object | |
| policy_id* | string | |
| measure_id | string | |
| intent_hash | string | |
| payment_ref* | string | Your internal payment reference, never an account number. |
| released_at | string | ISO timestamp; defaults to now. |
| released_by* | object | |
| agent_approval | object | Agent releases only: { id, role } of the person who signed off a release above the policy's agent_autonomy.release_up_to. The role is the policy's agent_autonomy.approver_role. |
{
"type": "object",
"required": [
"policy_id",
"payment_ref",
"released_by"
],
"properties": {
"uetr": {
"type": "string",
"description": "The payment's SWIFT UETR (UUID v4), optional: ties the record to the payment itself."
},
"amount": {
"type": "object",
"properties": {
"value": {
"type": "number"
},
"currency": {
"type": "string"
}
}
},
"map_id": {
"type": "string"
},
"exception": {
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"approved_by": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string"
}
}
}
}
},
"policy_id": {
"type": "string"
},
"measure_id": {
"type": "string"
},
"intent_hash": {
"type": "string"
},
"payment_ref": {
"type": "string",
"description": "Your internal payment reference, never an account number."
},
"released_at": {
"type": "string",
"description": "ISO timestamp; defaults to now."
},
"released_by": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"human",
"system",
"agent"
],
"type": "string"
}
}
},
"agent_approval": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string"
}
},
"description": "Agent releases only: { id, role } of the person who signed off a release above the policy's agent_autonomy.release_up_to. The role is the policy's agent_autonomy.approver_role."
}
}
}Read a Release Evidence Record by rer_id: the policy result at release and the reconcile status as of now (pending, done, overdue or not required). With no rer_id, verifies the organisation's chain of records and returns ok or the first record where it breaks. Read-only. Needs the organisation's key.
| Argument | Type | Description |
|---|---|---|
| rer_id | string |
{
"type": "object",
"properties": {
"rer_id": {
"type": "string"
}
}
}Keyed. Deletes a connected rail account and its stored credentials. Payments already sent stay readable in the business's own rail account.
| Argument | Type | Description |
|---|---|---|
| access_key | string | |
| connection_id* | string |
{
"type": "object",
"required": [
"connection_id"
],
"properties": {
"access_key": {
"type": "string"
},
"connection_id": {
"type": "string"
}
}
}Retired on 19 Oct 2026: SwapEazi collects no contact details for introductions. Calls answer RETIRED. The next step after route_intent is the chosen route's handoff_url, the provider's own sign-in or account page.
No arguments.
{
"type": "object",
"properties": {}
}For a payment run: the payments awaiting approval with amount, route, assessment and approval_digest, the approver role, and the payments not ready with their lifecycle state and reason. Never approves: a named person approves with approve_payment_run.
| Argument | Type | Description |
|---|---|---|
| run_id* | string | The payment run (pr_...), or pr_sample. |
| access_key | string | The router key that made the run. |
{
"type": "object",
"required": [
"run_id"
],
"properties": {
"run_id": {
"type": "string",
"description": "The payment run (pr_...), or pr_sample."
},
"access_key": {
"type": "string",
"description": "The router key that made the run."
}
}
}Route one cross-border payment, given as fields or as one sentence ("USD 25,000 to a supplier in Lagos by 30 November"). From a sentence the guide reads what matters without being told: urgency or the due date sets the deadline and puts speed first, words such as cheapest put cost first, regulated or licensed keeps only providers with a licence on record, and paying drivers, staff or a supplier is noted; intent.understood says what was read, and explicit policy fields override it. Returns every route that can carry it, ordered by the payer's own policy, the route the policy selects on the strongest evidence (payments measured when they landed, then published prices; estimates only if the policy allows), the saving against the payer's own quote, and where to pay. With a due date it also routes across time: pay now, lock a forward while holding tokenised T-bills, convert and park, or hold unhedged, as what each needs today. With remember: true SwapEazi keeps the intent, reprices it daily until due and returns its intent_id. A sentence about idle money ("park $5m USDC, back within 24 hours, non-US, qualified, we have Ondo") returns treasury parking instead: tokenised T-bill funds that fit the amount, eligibility, chain and redemption need, by net yield, with what the accounts already held can do and what a new account is worth. The free verification returns the verdict with names masked; a router key (Bearer rk_...) unlocks them. SwapEazi executes nothing and takes no fee from any provider. Returns a compact view by default (each route with its release window cut to the summary and landing dates); pass detail: "full" for everything.
| Argument | Type | Description |
|---|---|---|
| to | string | |
| from | string | |
| have | array | Providers or issuers the payer already has accounts with; the result shows what they can do and what a new account adds. |
| text | string | The payment in one sentence; used instead of from/to/amount. |
| amount | number | Amount leaving, in the source currency. |
| detail | string | compact (default): a short summary that points at the signed full document, sized for a tool result. full: the whole document, which can exceed 100 KB. |
| policy | object | |
| repeat | string | With remember and due_date: the payment repeats; due_date is the first cycle. Monthly cycles keep the day of month (31st: last day of shorter months). One reminder per cycle, before the last day to release through the selected route. |
| deliver | number | Amount to deliver on the due date, destination currency. |
| lock_at | number | With remember: mark the day locking the rate needs this much or less, source currency. |
| due_date | string | YYYY-MM-DD the money must land; adds routing across time: pay now, forward, convert and park, hold unhedged. |
| remember | boolean | Keep the intent and reprice it daily until it lands; returns remembered.intent_id. |
| repeat_count | number | With repeat: number of cycles, the first included. |
| repeat_until | string | With repeat: YYYY-MM-DD, last date a cycle may fall on. |
| nudge_lead_days | number | With repeat: banking days before the release-by date to send the reminder (default 2). |
| your_quote_landed | number | What the payer's current quote would land, in the destination currency. |
{
"type": "object",
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"have": {
"type": "array",
"items": {
"type": "string"
},
"description": "Providers or issuers the payer already has accounts with; the result shows what they can do and what a new account adds."
},
"text": {
"type": "string",
"description": "The payment in one sentence; used instead of from/to/amount."
},
"amount": {
"type": "number",
"description": "Amount leaving, in the source currency."
},
"detail": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "compact (default): a short summary that points at the signed full document, sized for a tool result. full: the whole document, which can exceed 100 KB."
},
"policy": {
"type": "object",
"properties": {
"risk": {
"enum": [
"certain",
"allow_unhedged"
],
"type": "string"
},
"exclude": {
"type": "array",
"items": {
"type": "string"
}
},
"objective": {
"enum": [
"lowest_cost",
"fastest"
],
"type": "string"
},
"deadline_days": {
"type": "number"
},
"max_all_in_bps": {
"type": "number"
},
"require_licence": {
"type": "boolean"
},
"include_estimates": {
"type": "boolean"
}
}
},
"repeat": {
"enum": [
"weekly",
"monthly"
],
"type": "string",
"description": "With remember and due_date: the payment repeats; due_date is the first cycle. Monthly cycles keep the day of month (31st: last day of shorter months). One reminder per cycle, before the last day to release through the selected route."
},
"deliver": {
"type": "number",
"description": "Amount to deliver on the due date, destination currency."
},
"lock_at": {
"type": "number",
"description": "With remember: mark the day locking the rate needs this much or less, source currency."
},
"due_date": {
"type": "string",
"description": "YYYY-MM-DD the money must land; adds routing across time: pay now, forward, convert and park, hold unhedged."
},
"remember": {
"type": "boolean",
"description": "Keep the intent and reprice it daily until it lands; returns remembered.intent_id."
},
"repeat_count": {
"type": "number",
"description": "With repeat: number of cycles, the first included."
},
"repeat_until": {
"type": "string",
"description": "With repeat: YYYY-MM-DD, last date a cycle may fall on."
},
"nudge_lead_days": {
"type": "number",
"description": "With repeat: banking days before the release-by date to send the reminder (default 2)."
},
"your_quote_landed": {
"type": "number",
"description": "What the payer's current quote would land, in the destination currency."
}
}
}The Payment Run. Send the payables (payables: a JSON list; file: a payout CSV or pain.001; or xero: a Xero bills reply) with source_currency. Each payment is verified (changed bank details against previous, duplicates, missing fields), assessed (route assessment_id with Rate Receipts: who published each figure, when it was read, its evidence type) and given an instruction for the business's own bank, provider or wallet (a CSV row, or an unsigned stablecoin transaction). Each is prepared, needs_attention (with the reason) or no_evidence. Returns run_id. An agent prepares; a named person approves. Never sends or moves money. A router key runs real payables; without one, sample: true returns the synthetic sample run. Same as POST /api/v1/payment-runs.
| Argument | Type | Description |
|---|---|---|
| file | string | Instead of payables: a payout CSV or pain.001 text. |
| sort | string | Your chosen order for the routes: landed cost against the official rate, stated days to land, or the measured 7-day answer rate. It is your order, stated as yours; SwapEazi does not rank routes. |
| policy | object | { approver_role, material_threshold: { amount, currency }, agent_may_record_approval } |
| sample | boolean | true: the built-in sample run (synthetic, labelled), no key needed. |
| payables | array | [{ reference, payee: { name, iban?, bic?, account_number?, routing_number?, branch_code?, country? }, amount, currency, due_date?, rail?: bank | provider | stablecoin, via?, wallet? }] |
| previous | array | The previous run's payables, for changed bank details and amount jumps. Not kept. |
| access_key | string | A router key (rk_...), if not sent as a Bearer header. |
| exclude_types | array | Leave out routes of these rail types. Each route left out is listed with the reason. |
| include_types | array | Keep only routes of these rail types. Each route left out is listed with the reason. |
| min_answer_rate | number | Percent, 0 to 100: leave out routes whose measured 7-day answer rate is lower, or not measured (not enough reads). Each is listed with the reason. |
| source_currency | string | The currency the business pays from, e.g. ZAR. |
{
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "Instead of payables: a payout CSV or pain.001 text."
},
"sort": {
"enum": [
"landed_cost",
"arrival_time",
"answer_rate"
],
"type": "string",
"description": "Your chosen order for the routes: landed cost against the official rate, stated days to land, or the measured 7-day answer rate. It is your order, stated as yours; SwapEazi does not rank routes."
},
"policy": {
"type": "object",
"description": "{ approver_role, material_threshold: { amount, currency }, agent_may_record_approval }"
},
"sample": {
"type": "boolean",
"description": "true: the built-in sample run (synthetic, labelled), no key needed."
},
"payables": {
"type": "array",
"items": {
"type": "object"
},
"description": "[{ reference, payee: { name, iban?, bic?, account_number?, routing_number?, branch_code?, country? }, amount, currency, due_date?, rail?: bank | provider | stablecoin, via?, wallet? }]"
},
"previous": {
"type": "array",
"items": {
"type": "object"
},
"description": "The previous run's payables, for changed bank details and amount jumps. Not kept."
},
"access_key": {
"type": "string",
"description": "A router key (rk_...), if not sent as a Bearer header."
},
"exclude_types": {
"type": "array",
"items": {
"enum": [
"banks",
"otc_desks",
"exchange_books",
"stablecoin_pools",
"p2p",
"ramps",
"payment_providers"
],
"type": "string"
},
"description": "Leave out routes of these rail types. Each route left out is listed with the reason."
},
"include_types": {
"type": "array",
"items": {
"enum": [
"banks",
"otc_desks",
"exchange_books",
"stablecoin_pools",
"p2p",
"ramps",
"payment_providers"
],
"type": "string"
},
"description": "Keep only routes of these rail types. Each route left out is listed with the reason."
},
"min_answer_rate": {
"type": "number",
"description": "Percent, 0 to 100: leave out routes whose measured 7-day answer rate is lower, or not measured (not enough reads). Each is listed with the reason."
},
"source_currency": {
"type": "string",
"description": "The currency the business pays from, e.g. ZAR."
}
}
}Sends ONE approved, released payment of a run through the business's own connected rail account (sandbox), with an idempotency key; without connection_id it reads the submission's status. Refused unless approved and within the connection's cap. Production execution waits on an authorised provider agreement.
| Argument | Type | Description |
|---|---|---|
| run_id* | string | The payment run (pr_...), or pr_sample. |
| account | string | The payee account the person approved, to match. |
| access_key | string | The router key that made the run. |
| payment_id* | string | |
| connection_id | string |
{
"type": "object",
"required": [
"run_id",
"payment_id"
],
"properties": {
"run_id": {
"type": "string",
"description": "The payment run (pr_...), or pr_sample."
},
"account": {
"type": "string",
"description": "The payee account the person approved, to match."
},
"access_key": {
"type": "string",
"description": "The router key that made the run."
},
"payment_id": {
"type": "string"
},
"connection_id": {
"type": "string"
}
}
}Structural check on a payment destination: an IBAN's own checksum (ISO 7064 MOD 97-10), a US ABA routing number's own checksum, a BIC's format (ISO 9362), an EVM address's EIP-55 checksum, a South African universal branch code recognised against known major banks, or a SADC mobile-money number (South Africa, Zimbabwe, Malawi, Zambia) assessed for the right country code and length. Catches a mistyped or mis-keyed identifier, the single most common cause of a misdirected payment. A payment platform is several rails at once (SEPA, Fedwire/ACH, stablecoin); this assessments whichever identifiers you supply. UK sort codes and most domestic account numbers carry no public checksum and are not covered. This is NOT confirmation of payee or verification of payee: it does not confirm the name on the account, only that the identifier is internally consistent (or, for a branch code or phone number, plausible). Paid: configure this server with an Authorization Bearer key (https://swapeazi.io/pricing).
| Argument | Type | Description |
|---|---|---|
| bic | string | A BIC/SWIFT code, 8 or 11 characters. |
| iban | string | An IBAN, spaces allowed. |
| address | string | An EVM address, '0x' followed by 40 hex characters. |
| mxClabe | string | A Mexican CLABE (SPEI account), 18 digits; its verification digit is verified. |
| mobileMoney | object | A SADC mobile-money number. |
| saBranchCode | string | A South African universal branch code, 6 digits. |
| usRoutingNumber | string | A US ABA routing number, 9 digits. |
{
"type": "object",
"properties": {
"bic": {
"type": "string",
"description": "A BIC/SWIFT code, 8 or 11 characters."
},
"iban": {
"type": "string",
"description": "An IBAN, spaces allowed."
},
"address": {
"type": "string",
"description": "An EVM address, '0x' followed by 40 hex characters."
},
"mxClabe": {
"type": "string",
"description": "A Mexican CLABE (SPEI account), 18 digits; its verification digit is verified."
},
"mobileMoney": {
"type": "object",
"required": [
"phone",
"country"
],
"properties": {
"phone": {
"type": "string",
"description": "E.164 format, e.g. +27821234567."
},
"country": {
"enum": [
"ZA",
"ZW",
"MW",
"ZM"
],
"type": "string"
}
},
"description": "A SADC mobile-money number."
},
"saBranchCode": {
"type": "string",
"description": "A South African universal branch code, 6 digits."
},
"usRoutingNumber": {
"type": "string",
"description": "A US ABA routing number, 9 digits."
}
}
}Documented status of cross-border corridors per provider: which pairs a provider says it serves, published fees, and when each record was last verified. Public tier only. Free, no key.
| Argument | Type | Description |
|---|---|---|
| to | string | Optional ISO 4217 destination currency, e.g. 'ZMW'. |
| from | string | Optional ISO 4217 source currency, e.g. 'ZAR'. |
| provider | string | Optional provider id. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "Optional ISO 4217 destination currency, e.g. 'ZMW'."
},
"from": {
"type": "string",
"description": "Optional ISO 4217 source currency, e.g. 'ZAR'."
},
"provider": {
"type": "string",
"description": "Optional provider id."
}
}
}Every currency a payment can be measured in today, and the number of directional corridors between them. Call before swapeazi_landed_cost to know whether a pair is covered. Free, no key.
No arguments.
{
"type": "object",
"properties": {}
}What a stablecoin swap on a DEX really cost, from its transaction hash: the sender's token out and token in, each priced as the currency it tracks (USDC, EURC, cUSD, KESm/cKES, cNGN, NGNm, ZARm, GHSm, XOFm, ZARP and others), measured against the independent reference for the day with a margin of error, and signed. Chains: ethereum, base, arbitrum, optimism, polygon, celo, robinhood. Free.
| Argument | Type | Description |
|---|---|---|
| tx* | string | The swap's transaction hash, 0x followed by 64 hex characters. |
| chain* | string | ethereum, base, arbitrum, optimism, polygon, celo or robinhood. |
{
"type": "object",
"required": [
"chain",
"tx"
],
"properties": {
"tx": {
"type": "string",
"description": "The swap's transaction hash, 0x followed by 64 hex characters."
},
"chain": {
"type": "string",
"description": "ethereum, base, arbitrum, optimism, polygon, celo or robinhood."
}
}
}The estimated fair forward rate for a currency pair and tenor, by covered interest parity from an independent mid and central bank policy rates, with its margin of error, and what hedging costs or earns per year. Free. With a paid key and quotedRate, the forward a bank quoted is held to it: how much is margin.
| Argument | Type | Description |
|---|---|---|
| to* | string | ISO 4217 code of the currency received, e.g. 'ZAR'. |
| from* | string | ISO 4217 code of the currency sold forward, e.g. 'USD'. |
| amount | number | Optional notional in the from currency, to state the margin in money. |
| tenorDays* | number | Days to settlement, 1 to 1095. |
| quotedRate | number | Optional. The forward rate a bank quoted (units of to per from). |
{
"type": "object",
"required": [
"from",
"to",
"tenorDays"
],
"properties": {
"to": {
"type": "string",
"description": "ISO 4217 code of the currency received, e.g. 'ZAR'."
},
"from": {
"type": "string",
"description": "ISO 4217 code of the currency sold forward, e.g. 'USD'."
},
"amount": {
"type": "number",
"description": "Optional notional in the from currency, to state the margin in money."
},
"tenorDays": {
"type": "number",
"description": "Days to settlement, 1 to 1095."
},
"quotedRate": {
"type": "number",
"description": "Optional. The forward rate a bank quoted (units of to per from)."
}
}
}Before money moves: every eligible route for a payment scored against your own limits (maximum LDI, maximum settlement time, regulated provider required), your quote measured if you pass one, beside what banks advertise, the official business-payment average and the G20 lines. Evidence against your policy, never a recommendation. Returns a signed decision record: keep it with the payment and pass it to swapeazi_guardrail_reconcile once it settles. Paid: configure this server with an Authorization Bearer key (https://swapeazi.io/pricing).
| Argument | Type | Description |
|---|---|---|
| quote | object | Optional. A quote you already hold, to be measured as given. |
| client_id | string | Optional. Your own reference, echoed back. |
| source_amount* | number | Amount to send, in the origin currency. |
| origin_currency* | string | ISO 4217 code, e.g. 'GBP'. |
| allowed_providers | array | Optional. Restrict routes to your own already-connected panel, by provider label or id. For embedding this assessment as a mandatory step inside your own already-licensed release pipeline — asking which of YOUR connected providers should carry this, not who exists in the market, the way an execution-management system asks which of its own connected brokers should fill an order. A provider outside the panel is ruled out before scoring, never silently dropped: it appears in ruled_out with reason not_in_callers_connected_panel. Omit for no restriction. |
| origin_jurisdiction | string | Optional ISO 3166-1 alpha-2 country of the sender. |
| destination_currency* | string | ISO 4217 code, e.g. 'MZN'. |
| max_settlement_hours | number | Optional. Your delivery-time cap. |
| require_regulated_lp | boolean | Default true. |
| max_acceptable_ldi_bps | number | Optional. Your cost cap in basis points. |
| destination_jurisdiction | string | Optional ISO 3166-1 alpha-2 country of the beneficiary. |
{
"type": "object",
"required": [
"origin_currency",
"destination_currency",
"source_amount"
],
"properties": {
"quote": {
"type": "object",
"required": [
"landed_amount"
],
"properties": {
"provider": {
"type": "string"
},
"landed_amount": {
"type": "number",
"description": "Amount the quote says will land, in the destination currency.",
"exclusiveMinimum": 0
}
},
"description": "Optional. A quote you already hold, to be measured as given."
},
"client_id": {
"type": "string",
"description": "Optional. Your own reference, echoed back."
},
"source_amount": {
"type": "number",
"description": "Amount to send, in the origin currency.",
"exclusiveMinimum": 0
},
"origin_currency": {
"type": "string",
"description": "ISO 4217 code, e.g. 'GBP'."
},
"allowed_providers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional. Restrict routes to your own already-connected panel, by provider label or id. For embedding this assessment as a mandatory step inside your own already-licensed release pipeline — asking which of YOUR connected providers should carry this, not who exists in the market, the way an execution-management system asks which of its own connected brokers should fill an order. A provider outside the panel is ruled out before scoring, never silently dropped: it appears in ruled_out with reason not_in_callers_connected_panel. Omit for no restriction."
},
"origin_jurisdiction": {
"type": "string",
"description": "Optional ISO 3166-1 alpha-2 country of the sender."
},
"destination_currency": {
"type": "string",
"description": "ISO 4217 code, e.g. 'MZN'."
},
"max_settlement_hours": {
"type": "number",
"description": "Optional. Your delivery-time cap.",
"exclusiveMinimum": 0
},
"require_regulated_lp": {
"type": "boolean",
"description": "Default true."
},
"max_acceptable_ldi_bps": {
"type": "number",
"minimum": 0,
"description": "Optional. Your cost cap in basis points."
},
"destination_jurisdiction": {
"type": "string",
"description": "Optional ISO 3166-1 alpha-2 country of the beneficiary."
}
}
}After money moves: the signed decision record from swapeazi_guardrail_check plus what landed (figures, or the bank's MT103 or pacs.008 text) returns a signed reconciliation. Was the quote honoured, did the payment stay inside policy, how far the market moved between approval and value date, and which part of the cost the banks in the chain took. Only amounts, dates, rates and charges are read from a message, never the parties. Paid, included in the assessment it closes.
| Argument | Type | Description |
|---|---|---|
| message | string | Optional. The bank's MT103 text or pacs.008 XML for this payment. |
| settlement | object | What landed, when no bank message is supplied. |
| attestation* | string | decision.attestation from swapeazi_guardrail_check. |
{
"type": "object",
"required": [
"attestation"
],
"properties": {
"message": {
"type": "string",
"description": "Optional. The bank's MT103 text or pacs.008 XML for this payment."
},
"settlement": {
"type": "object",
"required": [
"landed_amount"
],
"properties": {
"settled_on": {
"type": "string",
"description": "Optional. Value date, YYYY-MM-DD."
},
"landed_amount": {
"type": "number",
"description": "Amount that arrived, in the destination currency.",
"exclusiveMinimum": 0
},
"source_amount": {
"type": "number",
"description": "Optional. Amount that left, including any fee billed on top.",
"exclusiveMinimum": 0
}
},
"description": "What landed, when no bank message is supplied."
},
"attestation": {
"type": "string",
"description": "decision.attestation from swapeazi_guardrail_check."
}
}
}What a single cross-border payment costs, in basis points, against an independent mid-market reference: give the amount sent, the amount that landed (or a provider says will land) and the date. Returns the Landed Drag Index with its margin of error and the evidence tier. Free, no key.
| Argument | Type | Description |
|---|---|---|
| midSpot | number | Optional. Your own mid, destination units per source unit. Omit to use SwapEazi's reference. |
| settledOn | string | ISO date the payment settled. Omit it (or pass a future date) for a quote not yet accepted: it is measured against today's reference. |
| inputAmount* | number | Amount sent, in the source currency. |
| netLandedFiat* | number | Amount that landed or will land, in the destination currency, after every deduction. |
| sourceCurrency* | string | ISO 4217 code the payment is funded in, e.g. 'GBP'. |
| destinationCurrency* | string | ISO 4217 code the payment lands in, e.g. 'EUR'. |
{
"type": "object",
"required": [
"sourceCurrency",
"destinationCurrency",
"inputAmount",
"netLandedFiat"
],
"properties": {
"midSpot": {
"type": "number",
"description": "Optional. Your own mid, destination units per source unit. Omit to use SwapEazi's reference."
},
"settledOn": {
"type": "string",
"description": "ISO date the payment settled. Omit it (or pass a future date) for a quote not yet accepted: it is measured against today's reference."
},
"inputAmount": {
"type": "number",
"description": "Amount sent, in the source currency.",
"exclusiveMinimum": 0
},
"netLandedFiat": {
"type": "number",
"description": "Amount that landed or will land, in the destination currency, after every deduction.",
"exclusiveMinimum": 0
},
"sourceCurrency": {
"type": "string",
"description": "ISO 4217 code the payment is funded in, e.g. 'GBP'."
},
"destinationCurrency": {
"type": "string",
"description": "ISO 4217 code the payment lands in, e.g. 'EUR'."
}
}
}The same payment sent two to four ways (a bank wire, a payment provider, a stablecoin route through an on-ramp and an off-ramp), each measured end to end against one independent reference: what left, what landed, each route's cost with a margin of error, and the exact gap between them. The rail does not change the method. Free within the daily allowance.
| Argument | Type | Description |
|---|---|---|
| to* | string | ISO 4217 code of the currency that landed, e.g. 'KES'. |
| date | string | Optional payment date, YYYY-MM-DD. Defaults to today (a quote). |
| from* | string | ISO 4217 code of the currency that left, e.g. 'ZAR'. |
| sent | number | Optional amount sent, shared by every route that does not state its own. |
| routes* | array | Two to four routes. Each: label, landed (in the to currency), and optionally sent and fee (both in the from currency). |
| annualVolume | number | Optional yearly volume on this route in the from currency, to state the gap per year. |
{
"type": "object",
"required": [
"from",
"to",
"routes"
],
"properties": {
"to": {
"type": "string",
"description": "ISO 4217 code of the currency that landed, e.g. 'KES'."
},
"date": {
"type": "string",
"description": "Optional payment date, YYYY-MM-DD. Defaults to today (a quote)."
},
"from": {
"type": "string",
"description": "ISO 4217 code of the currency that left, e.g. 'ZAR'."
},
"sent": {
"type": "number",
"description": "Optional amount sent, shared by every route that does not state its own."
},
"routes": {
"type": "array",
"items": {
"type": "object",
"required": [
"landed"
],
"properties": {
"fee": {
"type": "number"
},
"sent": {
"type": "number"
},
"label": {
"type": "string"
},
"landed": {
"type": "number"
}
}
},
"description": "Two to four routes. Each: label, landed (in the to currency), and optionally sent and fee (both in the from currency)."
},
"annualVolume": {
"type": "number",
"description": "Optional yearly volume on this route in the from currency, to state the gap per year."
}
}
}Every tokenised Treasury and money fund SwapEazi covers (BUIDL, BENJI, OUSG, USTB, USYC, WTGXX, USDY, Spiko, CETES), landed in the investor's own currency and hedged back: after the fee, converting in and out at their size and the hedge carry, ranked, beside a local money fund, with a one-line verdict. Landed yields free; the working with a paid key.
| Argument | Type | Description |
|---|---|---|
| amount* | number | Amount to place, in the investor's currency. |
| horizonMonths | number | Holding period in months, default 12. |
| investorCurrency* | string | ISO 4217 code the investor holds and reports in, e.g. 'ZAR'. |
{
"type": "object",
"required": [
"investorCurrency",
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount to place, in the investor's currency."
},
"horizonMonths": {
"type": "number",
"description": "Holding period in months, default 12."
},
"investorCurrency": {
"type": "string",
"description": "ISO 4217 code the investor holds and reports in, e.g. 'ZAR'."
}
}
}Verify that a decision or reconciliation record was issued by SwapEazi and has not been altered, and read what it says. Free and keyless, so an auditor, board or counterparty can verify a payer's records without an account.
| Argument | Type | Description |
|---|---|---|
| attestation* | string | The attestation string from a decision or reconciliation. |
{
"type": "object",
"required": [
"attestation"
],
"properties": {
"attestation": {
"type": "string",
"description": "The attestation string from a decision or reconciliation."
}
}
}Spec v1.0 name for payment_run_status: each payment's lifecycle state (CREATED, ANALYSED, QUOTED, ROUTE_SELECTED, AWAITING_APPROVAL, APPROVED, SUBMITTED, PROCESSING, SETTLED, FAILED, REJECTED, EXPIRED, CANCELLED, REQUIRES_REVIEW) with the reason. SETTLED only on the provider's own confirmation.
| Argument | Type | Description |
|---|---|---|
| run_id* | string | The payment run (pr_...), or pr_sample. |
| access_key | string | The router key that made the run. |
{
"type": "object",
"required": [
"run_id"
],
"properties": {
"run_id": {
"type": "string",
"description": "The payment run (pr_...), or pr_sample."
},
"access_key": {
"type": "string",
"description": "The router key that made the run."
}
}
}Verify a SwapEazi Release Record v1, the evidence of a managed payment (or a chain of them), with no key: schema (https://swapeazi.io/schemas/release-record-v1.json), hash, chain link and Ed25519 signature against the published key. Returns valid or invalid with each test named and the first record that breaks. Nothing sent is stored. The same verification runs offline from the spec at https://swapeazi.io/standard.
| Argument | Type | Description |
|---|---|---|
| chain | array | Optional. The records around it, in any order; links are verified in seq order. |
| record | object | One release record, as returned by record_release, release_status or GET /api/v1/releases/{id}. |
{
"type": "object",
"properties": {
"chain": {
"type": "array",
"items": {
"type": "object"
},
"description": "Optional. The records around it, in any order; links are verified in seq order."
},
"record": {
"type": "object",
"description": "One release record, as returned by record_release, release_status or GET /api/v1/releases/{id}."
}
}
}We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Nov 5, 2026.
Takes a password, API key or token as an argument, so the secret passes through the model's context and chat logs.
Fix: Read credentials from the server's own configuration (environment, OAuth) instead of a tool argument.
No readOnlyHint / destructiveHint annotations, so clients can't tell a read from a write without asking.
Fix: Add annotations to each tool, e.g. { readOnlyHint: true } for tools that only read.