Payment Discovery
discover_paymentStarts a cross-border payment: prices it on every rail (bank, PSP, stablecoin) and lists what is not known, before anything is prepared. 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| payer | No | Optional. Who is paying: { entity_type, jurisdiction }. | |
| amount | Yes | The amount, greater than zero. | |
| client | No | Optional. Who is asking: { type: agent | human, agent_id }. | |
| detail | No | 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 | No | Which currency amount is stated in. Overrides direction's default, e.g. paying a fixed destination amount while funding from the source currency. | |
| direction | No | pay (default): amount is what leaves. receive: amount is what must land. | |
| needed_by | No | 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 | No | 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 | No | Optional. The payer's own limits: { max_settlement_hours, exclude_providers, require_licensed_in }. | |
| current_quote | No | Optional: a quote already held, measured as given against the reference. | |
| rails_allowed | No | Default: all. Only bank and stablecoin filter directly today; psp/dex leave every non-excluded rail in. | |
| source_currency | Yes | ISO 4217 code the payment leaves in, e.g. 'EUR'. | |
| target_currency | Yes | ISO 4217 code the payment must land in, e.g. 'ZAR'. |