Look up correspondent banking / settlement instructions (SSI) for a bank.
Returns the correspondent banks (nostro accounts) that a given bank
uses to settle payments in a specific currency, including account
numbers (when available) and intermediary chains. Essential for
payment routing and pre-validation.
Each correspondent is annotated with a clearing_note indicating
whether it can clear the currency directly (located in a home
country for that currency) or needs its own correspondent.
If the note suggests a further lookup, call ssi_lookup on the
correspondent's SWIFT code to find the full clearing chain.
IMPORTANT — known data gaps to respect:
- Account numbers may be empty for some/all correspondents. The
response surfaces an `account_availability_note` in those cases.
Do NOT invent account numbers. Use swift_lookup() to find the
bank's own published correspondent banks page when accounts
are missing.
- WHICH CORRESPONDENT: read `correspondent_selection`, not the array order.
It gives the COMPLETE set of BICs for each flow (customer MT103 vs
interbank MT202) and for whether the correspondent clears the currency
itself, each with a count. The correspondents are returned in STORAGE
order, which is not a ranking. Naming a subset ("principally X and Y",
"route via X") invents a preference this feed does not hold. Name every
BIC in the matching set, or give its count: which one is used is the
SENDING bank's choice among the ones it can already reach, not the
beneficiary bank's, and not ours to guess from bank size or reputation.
`is_preferred` is `null` on almost every row because the flag is
genuinely unrecorded (11 rows in the entire corpus carry it); where it IS
set, `correspondent_selection.bank_flagged_preference` names it and you
should lead with that.
- `intermediaries` is `null` — not `[]` — when this correspondent's onward
chain is not recorded, which is 98% of rows. `null` means NOT ESTABLISHED,
never zero hops: do not read it as a direct chain and do not count it.
Whether a further hop is needed is answered by each correspondent's
`clearing_note`, which says either that it clears the currency itself or
that a further hop is expected and gives the ssi_lookup call that resolves
it. When the chain IS recorded the array is populated and
`intermediaries_note` names the hops in order.
- Asset category per correspondent is COMMERCIAL (for customer
MT103 credit transfers) or FINANCIAL (for bank-own-account /
interbank MT202/pacs.009 settlements). Read `asset_categories`
(the full list) rather than the single `asset_category`, which
shows the commercial view only: one entry is one BIC+account and
the same account is often published under BOTH categories, so the
single field can never establish what an account may NOT be used
for. The `asset_category_note` summarises the split — match the
listed correspondents to the user's flow type (customer payment
vs treasury/interbank).
- If `correspondents` is EMPTY, we have no SSI on file for that
bank/currency. The response carries a `no_ssi_note` (no SSI in any
currency) or `requested_currency_unavailable_note` (SSI on file for
other currencies only). This is a coverage gap, NOT a finding that the
bank has no correspondents. Do NOT name a correspondent for the missing
currency from training data — surface the `published_ssi_document` /
the bank's website and tell the user to confirm SSI with the bank.
Always inspect the response's top-level `next_steps` array — it
chains the swift_lookup / country_banking_rules / bank_holidays
calls that complete a settlement-instruction answer.
COVERAGE IS KNOWABLE BEFORE YOU CALL, AND FOR FREE. swift_lookup returns a
`settlement_instructions` block on every bank: `on_file: true` with a
currency count means this lookup will answer, `false` means we hold none in
any currency, null means it has not been established. Do not treat "might be
a coverage gap" as a reason to skip the call and describe the routing from
memory — ask swift_lookup, then read the answer here.
Requires an API key with an active FI subscription.
To get started: call mcp_register → mcp_verify → subscribe to
an FI plan at https://ohmyfin.ai/subscription.
Examples:
ssi_lookup("DEUTDEFF", "USD") # Deutsche Bank USD correspondents
ssi_lookup("HSBCHKHH", "EUR") # HSBC HK EUR correspondents
ssi_lookup("DEUTDEFF", "USD", api_key="prod-abc123...")