Sokin MCP - Tool Guide - Sokin Embedded API

Every tool the Sokin MCP server offers: what it is for, what it needs from
you, and something to try asking. 26 tools, one section each, all in the
same shape so you can skim or search the page.

Start with the Sokin MCP — Setup and Usage Guide if you have not connected a
client yet. This page assumes you are connected and the balances prompt
worked.

You do not call these tools yourself. You ask your AI client for something in
plain English — "what are my balances", "show me last month's transactions on
the GBP account" — and it picks the tools and fills in the details. Each
section below tells you what a tool does, so you can recognise what is
happening and tell whether you got what you asked for.

These tools act on your live Sokin account. Most of them only read
data, but some move real money: sending a payment, and converting between
accounts. Your client asks you to confirm before either one runs, and
Moving money below explains how.

All 26 tools

In the order they appear below. Every tool's own section repeats its name as
a heading, so a browser find on the name jumps straight to it.

Tool	What it is for
`list_corporates`	Which companies your login can act for
`list_accounts`	A company's currency accounts and balances
`get_account`	One account in full, including pay-in details
`get_account_ledger`	Transaction history for an account
`list_beneficiaries`	Who a company can pay
`get_beneficiary`	One payee in full, with account details and verification
`get_beneficiary_schema`	What details a new payee needs
`validate_beneficiary`	Check payee details, or an e-Transfer email, before relying on them
`create_beneficiary`	Creates a new payee, behind an emailed code
`update_beneficiary`	Changes an existing payee, behind an emailed code
`list_financial_institutions`	Banks available when setting up a payee
`list_financial_institution_branches`	A bank's branches and routing numbers
`list_instructions`	Payments and conversions, listed
`get_instruction`	One payment or conversion in full
`get_instruction_request`	How a submitted payment actually turned out
`validate_payment_instruction`	Check a payment without sending it
`create_payment_instruction`	Prepare a payment for review. Sends nothing
`submit_payment_instruction`	Sends a real payment
`create_fx_payment_instruction`	Prepare a pay-in-another-currency payment. Sends nothing
`submit_fx_payment_instruction`	Sends a real payment, converting as it goes
`get_fx_quote`	Open the quote card for converting between your own accounts (no rate without cards)
`create_fx_quote`	Create a real, short-lived rate. Moves no money
`settle_fx_quote`	Converts real money between your own accounts
`visualize`	Draw a diagram or chart in the chat
`get_documentation_links`	Where Sokin's documentation lives
`play_cheetah_dash`	An arcade game, in the chat

What you can ask for

If you want to	The tools behind it
See which companies you can act for	`list_corporates`
See balances across accounts	`list_accounts`, `get_account`
See transaction history	`get_account_ledger`
Look up who you can pay	`list_beneficiaries`, `get_beneficiary`
Check a payee's details are right	`validate_beneficiary`
Add a payee, or change one's details	`get_beneficiary_schema`, then `create_beneficiary` or `update_beneficiary`
Look up a bank or branch	`list_financial_institutions`, `list_financial_institution_branches`
Check on payments already made	`list_instructions`, `get_instruction`, `get_instruction_request`
Check a payment before sending it	`validate_payment_instruction`
Send a payment	`create_payment_instruction`, then `submit_payment_instruction`
Pay someone in a currency you do not hold	`create_fx_payment_instruction`, then `submit_fx_payment_instruction`
Start a conversion between your own accounts (see the rate on a card)	`get_fx_quote`
Convert between your own accounts	`create_fx_quote`, then `settle_fx_quote`
Draw a chart or diagram of a result	`visualize`
Find Sokin's documentation	`get_documentation_links`

18 of the 26 only read data. The other eight change something, and three
of those move real money — keep your client asking you to confirm before any
of them runs. See Moving money.

Reading a result

Your assistant reads each tool's answer and tells you what it found, in a
sentence or a table. If you are building something on these tools and need
the exact shape of each answer, the Technical Docs has a worked example
for every tool.

Four tools return long lists a page at a time — get_account_ledger,
list_instructions, list_beneficiaries and
list_financial_institution_branches. When there is more, the result says so
and carries a token for the next page; your client handles this for you.

Which tools your client can use

Five tools draw an interactive card in the chat rather than plain
text — a review card with Approve and Cancel for each of the two ways of
paying someone, an exchange-rate card with a live countdown, a chart, and a
game. Claude on the web and desktop shows them; Claude Code, Replit and
ChatGPT do not. Clients change, so check
yours: ask for an exchange rate, and if a card appears and its Get
Quote button gives you a live rate, yours works with them. A card alone is
not proof — it can appear and still refuse to quote. If that happens, Sokin
has no current record that your client can show cards: reconnecting Sokin in
your client sends it again, and if Get Quote is still refused, convert in the
Sokin portal. Getting a quote moves no money.

This decides what you can do, not just how it looks:

	Client with cards	Client without
All the read-only tools	Work	Work
`get_fx_quote`	Interactive quote card	No rate and no quote, just a link to the Sokin portal to see the rate and trade
`create_fx_quote`, `settle_fx_quote`	Driven by the card's buttons	Not available
Paying a beneficiary, either pair	Review card with Approve	Works — you confirm in the chat
`visualize`, `play_cheetah_dash`	Render	Return their content as text

On a client without cards, everything works except the cards themselves and
converting between your own accounts. validate_payment_instruction is a
genuine dry run and safe to build on.

The two kinds of money movement differ:

Converting between your own accounts needs a card. Without one,
create_fx_quote and settle_fx_quote refuse to run, however they are
asked, and get_fx_quote gives you a link to the Sokin portal instead.

Paying a beneficiary works without a card, and is meant to. Your
assistant reads the payment back to you in the chat and asks for your
go-ahead before it submits anything.

What protects you is not the card. It is two things: your client asks you
before it runs any tool that changes something (keep that switched on), and
by default every payment
and conversion started here waits for approval in the Sokin portal (the
Setup and Usage Guide explains it, and when that can differ, under
Before you move money).

Moving money

Eight tools change something, and three of them move real money. Those
three are the ones this section is about; the other five — create_fx_quote,
create_fx_payment_instruction, validate_beneficiary, create_beneficiary
and update_beneficiary — write something without moving a penny. None of
the three that do move money is a single call you can stumble into: each is
the second half of a pair, and will only ever submit exactly what the first
half prepared.

Tool	What it does
`settle_fx_quote`	Converts real money between two of your own accounts
`submit_payment_instruction`	Sends a real payment to a beneficiary
`submit_fx_payment_instruction`	Sends a real payment, converting as it goes

Each is the second half of a pair: one tool prepares and shows you what
will happen, and the second submits it. The second will only ever send exactly
what was prepared — not a changed version, and not twice. An identical
payment is also refused for 12 hours after the first, even if that one was
later rejected.

Which pair you want depends on the currency:

You want to	Pair
Pay someone in a currency you hold	`create_payment_instruction` → `submit_payment_instruction`
Pay someone in a currency you do not hold	`create_fx_payment_instruction` → `submit_fx_payment_instruction`
Convert between two of your own accounts	`get_fx_quote` card → `create_fx_quote` → `settle_fx_quote`

What the pair does not do is prove that you, rather than your
assistant, said yes. Your assistant can see what it needs to submit what it
prepared, so keep your client asking before these tools run — never set
them to run without asking. By default, approval in the Sokin portal then
follows for every payment and conversion.

Sending a payment prepares in the conversation and commits from a review card:

Converting currency happens entirely inside one card, because an exchange rate
expires too quickly to survive a back-and-forth in chat:

Submitting is not the same as finished. Both flows hand back a receipt
reference, wait for approval in the Sokin portal, and do the work after that.
get_instruction_request confirms the payment or conversion was created;
get_instruction shows where it stands — waiting for approval, processed,
rejected or failed.

The tools, one by one

Each section below gives the tool's name, what it does, what it takes, and a
prompt to try. The exact request and reply for every tool are in the
Technical Docs.

Where a section mentions the Technical Docs, it means the Sokin MCP —
Technical Docs page, which carries the exact response schemas field by
field, every possible value of every coded field, and the error and pagination
contracts. This page is the guide; that one is the specification.

`list_corporates`

Lists the companies your login can act for. Usually the first call of any
session — nearly every other tool needs a corporate reference, and this is
where one comes from. Read-only.

Takes: nothing.

Try asking

Which companies can I act for in Sokin?

assignmentType is direct if you were given access to that company, or
inherited if it comes via a parent.

`list_accounts`

All of a company's currency accounts, with balances. Read-only.

Takes	Required	What it is
`corporate_reference`	yes	From `list_corporates`

Try asking

Show me all my Sokin accounts and their balances.

Balance and available balance are different numbers. Available is the
balance minus whatever is reserved by payments already in flight. It can come
back empty when your login lacks permission to see instructions; the answer
says so in words rather than showing a zero.

Neither number includes Boost. Money moved into Easy Access Boost or
Fixed Term Boost leaves this account's own balance entirely — this tool has
no visibility into Boost at all. The "Total Funds" figure in the Sokin
portal adds your Boost total on top of balance, so it will not match the
numbers here. get_account_ledger shows the movement itself: a Boost deposit appears
there with "Sokin Boost" as the counterparty, and money coming back from
Boost — an Easy Access withdrawal, or a Fixed Term Boost reaching or
leaving its term — appears as a boost_maturity_payout entry.

`get_account`

Everything about one account, including the bank details someone would use to
pay money into it. Read-only.

Takes	Required	What it is
`account_reference`	yes	An account reference from `list_accounts`

Try asking

What details should a customer use to pay into our GBP account?

An account can have local pay-in details, international ones, or neither set
up yet, so either can be missing. IBAN and BIC come back where they
apply.

Neither balance figure includes Boost, same as list_accounts above —
check there for what that means if a figure looks lower than expected.

`get_account_ledger`

Transaction history for one account, newest first, a page at a time.
Read-only.

Takes	Required	What it is
`account_reference`	yes	The account to look at
`from_date`	no	Only entries from this date (`YYYY-MM-DD`)
`to_date`	no	Only entries up to this date
`limit`	no	Entries per page (default 25, max 100)
`next_token`	no	Ask for the next page, using the token from the last one

Try asking

Show me the transactions on our GBP account since 1 August.

In the answer, money in shows as + and money out as −. The other party
is the sender for money in and the payee for money out.

Each entry has a type — deposits, withdrawals, FX trades and more — and not
every type has a friendly label. The Technical Docs list them all.

`list_beneficiaries`

Who a company can pay. Mostly used to check whether a payee already exists,
and to get the reference a payment needs. Read-only, a page at a time.

You can create and change a payee here, but not delete one.
create_beneficiary adds one and update_beneficiary changes its bank or
identity details, both behind an emailed confirmation code. Nothing in the
chat removes a payee; one deleted in the Sokin portal no longer appears
here. get_beneficiary_schema tells you what a new payee needs, and
validate_beneficiary checks details before you commit to them.

Takes	Required	What it is
`corporate_reference`	no, but effectively yes	The company whose payees you want
`search`	no	Match against the name. Leave out to list everyone
`search_mode`	no	`"contains"` (default) or `"starts_with"`
`limit`	no	Per page
`next_token`	no	Token from the previous page

Try asking

Do we already have Fabrikam GmbH as a payee?

A payee can be reachable in the same currency by more than one route — euros
over SEPA or SWIFT, say, which differ in speed and cost — so the answer shows
every route for each currency.

This tool also accepts page and offset, purely so it can tell you clearly
that they are not supported. Use limit and next_token.

`get_beneficiary`

One payee in full, by reference. Where list_beneficiaries collapses a payee
to its currency-and-route pairs, this returns each destination's actual
account details — account numbers, routing data, an e-Transfer email, a
crypto wallet address — plus how far each one has been verified. Read-only.

Takes	Required	What it is
`beneficiary_id`	yes	The payee's reference from `list_beneficiaries`
`corporate_reference`	no, but effectively yes	The company the payee belongs to

Try asking

Show me Fabrikam's bank details and whether they have been verified.

Check whether each route is verified before you pay someone.
matched means the account details were checked against the account holder's
name; not_validated means they were not. It is per destination, so the same
payee can be verified on one route and unverified on another.

One thing this never returns: for an e-Transfer destination without
auto-deposit, the security question comes back but the answer never does.
That answer is what the recipient has to give to claim the money.

`get_beneficiary_schema`

What details a new payee needs, for a given payment method, currency and
country — field names, types, which are required, and what values are allowed.
Use it to collect the right information before creating a payee, rather than
guessing and being rejected. Read-only.

Payment method here is a coarser grouping than the payment rails you
see elsewhere. Every rail belongs to exactly one method:

Method	Rails
`bank_account`	`faster_payments`, `sepa`, `swift`, `ach`, `eft`, and the rest
`e_transfer`	`e_transfer`
`virtual_account`	`pix`
`sokin_internal`	`internal`
`crypto`	`base`, `tron`, `ethereum`, `polygon`, `solana`

Takes	Required	What it is
`payment_method`	yes	One of the five above. `crypto` is always refused — Sokin cannot describe crypto payees here yet
`currency_code`	unless `sokin_internal`	Currency the payee is paid in
`country_code`	unless `sokin_internal`	Country of the payee's account
`entity_type`	unless `sokin_internal`	`individual` or `company`
`autodeposit_enrolled`	no	e-Transfer only: `"true"`, `"false"` or `"unknown"`. Pass `"unknown"` rather than omitting it when you have not checked — omitting behaves like `"true"` and leaves the security question optional
`corporate_reference`	no, but effectively yes	The company the payee will belong to

Try asking

What do I need to add a UK supplier we pay by Faster Payments?

The answer names each detail by where it goes, such as address.city or
bankAccount.accountNumber. "Only for rails" means required just for those
routes; "conditional on X" means it only applies once X has been
answered.

A currency and country your company has no payment route for is refused,
with a message saying so.

`validate_beneficiary`

Checks payee details before you rely on them — that an account number
really belongs to the name you were given, that an e-Transfer email can
receive money, or that an existing payee's details still check out. Run it
before creating a payee paid by UK account, IBAN or e-Transfer; see
create_beneficiary.

Exactly one check per call, and which fields you pass decides which:

To check	Pass
An existing payee, all destinations	`beneficiary_id`
Whether an e-Transfer email can auto-deposit	`email`
An IBAN against a name	`iban` + `bic` + `account_name`
A UK account against a name	`sort_code` + `account_number` + `account_name`

Takes	Required	What it is
`beneficiary_id`	for the first check	The payee's reference from `list_beneficiaries`
`email`	for the second	Recipient email to probe
`iban`	for the third	The IBAN, 15–34 characters
`bic`	for the third	BIC/SWIFT, 8 or 11 characters
`account_name`	third and fourth	The account holder name to verify
`sort_code`	for the fourth	UK sort code, 6 digits. Spaces and hyphens are fine
`account_number`	for the fourth	UK account number, 8 digits
`corporate_reference`	no, but effectively yes	The company to check under

Try asking

Check that sort code 12-34-56 and account 12345678 belong to Jane Okafor.

The overall result is the worst one, so a payee with one verified route
and one unverifiable one never reads as though everything passed. These
outcomes are easy to confuse:

Status	What it means
`matched`	The name checks out
`close_match`	Nearly — compare both names before going further
`no_match`, `invalid`	Not verified
`check_not_possible`, `not_validated`	The check did not run. Not a pass

Two things it cannot tell you. An e-Transfer result confirms auto-deposit
enrolment, not the account name. And not every route has a name check:
internal payees, and bank routes with no check available (most non-euro
ones, for example), come back not_validated, meaning "not applicable"
rather than "failed".

This is the only read-shaped tool here that writes. Checking an existing
payee saves each refreshed status back, which is why your client may ask
before running it. It moves no money, and re-running it produces the same
answer.

`create_beneficiary`

Creates a new payee, behind a one-time code emailed to you. This is one
tool you call twice.

You give the payee's details. They are checked first, so a mistake costs
nothing and sends no email. If your company requires a code, one is
emailed to you.

You give your assistant the code, and it sends exactly the same
details again with the code.

If your company does not require a code, the first call creates the payee.

Check the name first for UK and EU payees. Before creating a payee paid
by UK sort code and account number, or by IBAN, ask for a name check with
validate_beneficiary: Confirmation of Payee for a UK account, Verification
of Payee for an IBAN. It tells you whether the account really belongs to the
name you were given. Your assistant is asked to run it and to stop on a
mismatch, but nothing stops a payee being created without one, so if you
are not sure it ran, ask for it. For a new euro (SEPA) payee, also ask for a
re-check by its reference straight after creating it: a new payee starts
unchecked, and euro payments to it are blocked until a check has run.

Takes	Required	What it is
`display_name`	yes	Payee name, 1–255 characters
`currency_code`	yes	ISO 4217, or the stablecoin code for a crypto rail
`payment_rail`	yes	e.g. `faster_payments`, `sepa`, `swift`, `eft`, `e_transfer`, `internal`, `pix`
`entity_type`	unless rail `internal`	`individual` or `company`
`country_code`	unless rail `internal`	Country of the payee's account
one destination object	yes	`bank_account`, `e_transfer`, `virtual_account`, `sokin_internal` or `crypto` — whichever matches the rail. `get_beneficiary_schema` tells you the fields
`individual` / `company`	per `entity_type`	Identity details
`address`	bank rails and `e_transfer`	Not needed for `internal`, `pix` or crypto
`corporate_reference`	no, but effectively yes	The company to create under
`otp_code`	on the second call	The 6-character code from your email
`confirm_verified_payee_name`	no	Only after a name mismatch you have checked and accepted. It restarts the flow with a fresh code

Try asking

Add Contoso Ltd as a payee for GBP payments by Faster Payments.

Check list_beneficiaries first. There is no duplicate detection: add
the same payee twice and you get two payees.

About the code, because getting it wrong has consequences beyond this
tool:

It is 6 characters, single-use, and expires after 10 minutes.

Only the most recent email works. Each new code replaces the last one,
so if you asked for two, only the newer code works.

Five wrong attempts temporarily locks the account, including the Sokin
portal login. Never guess a code; read it from the latest email.

If anything changes between the two steps, including accepting a name
mismatch, the flow starts again with a fresh code.

`update_beneficiary`

Changes an existing payee's bank or identity details, behind the same
emailed one-time code as create_beneficiary. Called twice, like creating
one: once to trigger the code, once with the code to apply the change.
Unlike creating, there is no free check first, so a problem with the new
details only shows up after you have used the code.

Send only what changes. Anything you leave out stays as it was — and a
field cannot be emptied, only given a new value.

Four things cannot be changed at all: the payee's name, whether it is a
person or a company, its country, and its address. Those are fixed once the
payee exists; changing any of them means creating a new payee. The tool refuses
them straight away rather than letting you burn a code first.

Takes	Required	What it is
`beneficiary_id`	yes	The payee to change, from `list_beneficiaries`
`currency_code` + `payment_rail`	if the payee has more than one destination	Which destination you mean, not a change to it. Supply both together
`bank_account`, `e_transfer`, `virtual_account`, `sokin_internal`, `crypto`, `individual`, `company`	at least one	The fields to change
`corporate_reference`	no, but effectively yes	The company the payee belongs to
`otp_code`	on the second call	The 6-character code from your email
`confirm_verified_payee_name`	no	Only after a name mismatch you have checked and accepted. It restarts the flow with a fresh code

Try asking

Change Contoso's bank account number to 87654321.

A selector can add rather than change. If the currency and rail you name
are ones the payee does not have yet, and you send destination fields with
them, you add a new way of paying them instead of editing an existing one.
Both are legitimate, so make sure which one you mean.

After changing a euro (SEPA) route, ask for a re-check with
validate_beneficiary: the change resets that route to unchecked, and euro
payments to it are blocked until a check has run.

Two behaviours that surprise people:

A validation error can name fields you never sent. Sokin merges your
change into the stored payee and re-checks the whole result, so an error may
point at something that was already there.

An unknown payee fails before any code is used. Wrong beneficiary_id,
or the right one under the wrong company, both read as "not found" — and no
code is emailed or consumed, so nothing is wasted.

The code rules are the same as create_beneficiary's, including that five
wrong attempts temporarily locks the account. Never guess or retry a code.

`list_financial_institutions`

Reference data: banks available when setting up a payee, for the routes that
need one (Canadian EFT, for instance). Read-only, not filterable — the
underlying service takes no options, so neither does this.

Takes: nothing.

Try asking

Which Canadian banks can I pick from for an EFT payee?

Do not treat this as a complete list of valid banks. Some banks are
missing from it, so a bank you cannot find here may still be a real, usable
one.

`list_financial_institution_branches`

A bank's branches, with routing numbers and addresses, for completing a
payee's details. Read-only, a page at a time.

Takes	Required	What it is
`financial_institution_id`	yes	The id from `list_financial_institutions`
`limit`	no	Per page
`next_token`	no	Token from the previous page

Try asking

List the branches of Royal Bank of Canada.

An empty result can mean either an unrecognised bank id or a bank with no
branches listed. The tool checks the id itself and tells you which.

`list_instructions`

Payments and conversions for a company, or for one account. Read-only, a page
at a time.

Takes	Required	What it is
`corporate_reference`	one of these two	List for a whole company
`cca_reference`	one of these two	List for a single account
`completed`	no	Being phased out — `true` for finished (including failed ones — see below), `false` for still in progress
`exclude_display_status`	no	Leave out rows with this status: `Processed`, `Failed`, or both. Mutually exclusive with `completed`
`limit`	no	Per page (default 20, max 100)
`next_token`	no	Token from the previous page
`sort_order`	no	`desc` (default, newest first) or `asc` (oldest first)

Give exactly one of the first two — neither or both is an error.

completed means finished, not successful. completed=true includes
payments that failed as well as ones that succeeded, so asking
completed=false for what's still outstanding misses every failed one —
even though your own Transaction Queue shows those as needing attention.
Use exclude_display_status instead — completed is being phased out, so
this is the filter that will keep working: leaving out both Processed and
Failed gives you what's genuinely still in progress; leaving out just
Processed gives you everything that isn't a clean success, in-progress and
failed together. A payment rejected at approval shows here as Failed;
get_instruction shows it as Rejected.

Try asking

Which payments on our GBP account are still outstanding?

The account reference matters: a company can hold several accounts in the
same currency, so the currency alone does not tell you which one the money
came from.

`get_instruction`

Everything about one payment or conversion — status, amounts, fees, payee.
Read-only.

Takes	Required	What it is
`instruction_reference`	yes	The instruction to look up

Try asking

Show me everything about payment INS-5513.

This is where you see where a payment or conversion stands: waiting for
approval, processed, rejected at approval, or failed. Some details, such as
a failure reason, appear only when they apply. The full field list is in the
Technical Docs.

`get_instruction_request`

Whether a submitted payment or conversion was created. Submitting hands
back a receipt reference; this tells you whether Sokin created the payment
from it, is still creating it, or refused it. Being created is not the end:
the payment then waits for approval, and get_instruction shows where it
stands after that. Read-only.

Takes	Required	What it is
`instruction_request_reference`	yes	The receipt reference from submitting. Not an instruction reference — those go to `get_instruction`

Try asking

Did the payment I just sent go through?

Read the status carefully, because the words are misleading:

Status	What it actually means
`Created`	Still being created. Not a success yet
`Accepted`	Created. It now waits for approval — use `get_instruction` for where it stands
`Rejected`	Refused, and the reason is in the result. Nothing was created

A request still being processed says so and asks you to check again
shortly. A rejected one gives the reason, such as an insufficient balance.

If a reference comes back as not found, it is almost always the wrong
reference — commonly an instruction reference used here by mistake. The one
exception is a submission made seconds ago, which can briefly read as missing
while it is being saved; check once more, then stop.

`validate_payment_instruction`

Checks a payment without sending it. Runs the same checks as the real
thing — account, payee, balance, fees — and tells you whether it would work.
Nothing is saved and no money moves.

This is the tool to use before preparing a payment, and it is safe on any
client.

Takes	Required	What it is
`corporate_currency_account`	yes	The account to pay from
`beneficiary_reference`	yes	Who to pay, from `list_beneficiaries`
`amount`	yes	Plain decimal, up to 2 places, above zero (e.g. `"125.50"`)
`reseller_fee`	no	Same format, zero or more
`sender_reference`	no	Text the recipient sees, max 18 characters
`payment_purpose`	no	One of a fixed list of purpose codes, e.g. `ACCOUNTS_PAYABLE`. Any other value is refused
`amount_is_fees_inclusive`	no	`true` takes fees out of the amount; default adds them on top

Try asking

Check whether we could pay Contoso 1,250 GBP from our GBP account, without sending anything.

You usually get the costs even when it fails, which is what makes this useful for
checking affordability: a check that fails for lack of funds still tells you
the total that would be debited and the fees.

`create_payment_instruction`

Prepares a payment for you to look at. It does not send it. Despite the
name, no payment exists after this and no money has moved.

What it does: re-runs the checks so you see Sokin's own figures rather than
the assistant's, then shows you a review card with Approve and Cancel.
Only your Approve click sends anything. On a client without cards, your
assistant reads the payment back to you and asks for your go-ahead in the
chat instead.

Run validate_payment_instruction first and fix anything it flags. This
tool checks again itself, and if the check fails nothing is prepared.

Takes the same details as validate_payment_instruction.

Try asking

Pay Contoso 1,250 GBP from our GBP account.

If you sent this exact payment in the last 12 hours, even one that was
later rejected, the result says so
and the card appears with no Approve button. To pay the same person the
same amount again within that time on purpose, give it a different sender
reference, which makes it a different payment. There is no way to override
this, by design.

A prepared payment you never approve is never sent; after a day it can no
longer be approved, and you prepare it again.

Coming back to the conversation later. When you reopen a chat, the card
shows the payment's details straight away, but offers nothing until it has
checked with Sokin: where the Approve button goes, it says it is checking.
A payment you already approved
shows as Already submitted with its reference and no Approve button, and
the card then shows where it stands now: waiting for approval, completed,
rejected or failed. If a payment with the same details is still being
submitted, or Sokin never confirmed whether it went through, the card says it
may already have gone out and offers only Check again. An expired one says
so. If the check cannot reach Sokin, the card says it could not check and
offers to try again; it never offers Approve without an answer.

`submit_payment_instruction`

Sends the payment. This moves real money to someone else. The real
control is approval in your company's Sokin portal, not this tool: by
default the payment waits there until someone approves it. It cannot be cancelled from the chat
once sent.

Your Approve click on the review card runs this; on a client without cards,
your assistant runs it once you say yes in the chat. Either way it takes
nothing new: it only accepts a payment that was prepared and shown to you,
unchanged, and only once.

Try asking

Yes, that is right. Send it.

Say this once you have checked the prepared payment. On a client with cards,
click Approve on the card instead.

Submitting is not confirmation the payment succeeded. You get a receipt
reference: get_instruction_request confirms the payment was created, and
get_instruction then shows whether it was approved and processed.

What the server refuses, without sending anything:

A payment that was not prepared and shown to you first.

Any change to the amount, payee or reference after you saw it.

The same payment again within 12 hours of the first.

Two approvals racing each other; exactly one can win.

Approving the same payment twice — a double click, a retry — sends nothing
again. The tool looks up what happened the first time and tells you.

`create_fx_payment_instruction`

Pays a beneficiary in a currency you do not hold, converting and paying in
one motion. Prepares it for review — it submits nothing, and despite the
name no payment exists after this call.

Use it when the payee wants one currency and you are spending another. For a
payment in a currency you already hold, use create_payment_instruction
instead; for converting between two of your own accounts with no payee, use
the FX quote card.

You do not fetch a rate first. This tool creates its own live quote
from the currencies and amount you give it (a real one, which is why your
client asks before running it), then runs the same checks as a normal
payment, so a problem with the payee (missing, cannot receive that currency,
fails verification) is reported here rather than after someone clicks
Approve.

Takes	Required	What it is
`corporate_currency_account`	yes	The account to pay from
`beneficiary_reference`	yes	Who to pay, from `list_beneficiaries`
`buy_currency`	yes	What the beneficiary receives, e.g. `"USD"`
`sell_currency`	yes	What you are spending, e.g. `"GBP"`
`amount`	yes	The amount of whichever side `fixed_side` names
`fixed_side`	no	`"BUY"` or `"SELL"`. Default `"SELL"`
`corporate_reference`	no, but effectively yes	The company to quote for
`reseller_fee`	no	Plain decimal, zero or more
`sender_reference`	no	Text the recipient sees, max 18 characters
`payment_purpose`	no	One of a fixed list of purpose codes, e.g. `ACCOUNTS_PAYABLE`. Any other value is refused

Try asking

Pay Fabrikam 1,000 EUR from our GBP account.

Coming back to the conversation later works as it does for
create_payment_instruction: the card checks with Sokin first, and
reopening it creates no new quote. (Some clients reopen a card without its
earlier result; the card then prepares the payment again, with a new
quote.)

The quote can still expire after you approve. The payment then waits for
approval in the Sokin portal, which runs at human pace, and the portal will not
approve it once the quote has expired. The approver either rejects it
(Rejected) or takes a fresh rate, which closes this payment as Failed with
the reason FX quote expired at approval. You find out from the payment's
status, not as an error. If it was closed for a fresh rate, check the Sokin
portal before preparing it again: the approver may already have gone ahead
at the new rate. The card counts down to the quote's expiry.

`submit_fx_payment_instruction`

Sends the FX payment. This moves real money — it converts and pays a
beneficiary in one motion, and cannot be cancelled from the chat once
submitted.

It only sends the FX payment that create_fx_payment_instruction prepared
and showed you, unchanged. On a client with cards the Approve button runs it;
on a client without, your assistant runs it once you say yes in the chat.
Either way it takes nothing new.

Try asking

Yes, that is right. Send it.

Say this once you have checked the prepared payment. On a client with cards,
click Approve on the card instead.

It still needs approval. By default, a payment submitted here waits for
approval in the Sokin portal before it is processed; get_instruction shows when that
has happened.

Sending the same payment twice sends nothing again: the tool looks up what
happened the first time and tells you.

`get_fx_quote`

Asks what an exchange rate is. Never books anything and never moves money.

What you get back depends on your client:

A client with interactive cards gets a card covering the whole
flow — request, quote, settle — with a countdown. This call alone creates no
quote; the card's Get Quote button does. This call on its own shows no
rate.

A client without gets no rate and no quote: nothing is created. It gets
your request echoed back plus a link to the Sokin portal, where you see the
live rate and make the trade.

Why it works that way: a real quote expires in as little as two minutes,
set by whoever priced it. Creating one before a person has seen it would burn
most of that window before anyone could act.

Takes	Required	What it is
`buy_currency`	yes	What you are buying, e.g. `"USD"`
`sell_currency`	yes	What you are selling, e.g. `"GBP"`
`amount`	yes	The amount of whichever side `fixed_side` names
`fixed_side`	no	`"BUY"` or `"SELL"`. Default `"SELL"`
`corporate_reference`	yes	Which company to quote for. From `list_corporates`
`corporate_currency_account`	no	The account a later conversion would come from

Try asking

Convert 1,000 GBP to USD between our own accounts.

Coming back to the conversation later. When you reopen a chat, the card
checks with Sokin what already happened on it before it offers anything.
That check prices nothing and sends nothing. A settled conversion shows as
submitted, with its IR- reference, and the card carries on tracking it,
including its wait for approval in the Sokin portal. A quote that is still
live comes back with its countdown and Settle button. A quote that expired
with nothing settled offers Get Quote again. If a settlement may still be
going through, or ended without a clear answer, the card offers neither
button and asks you to check first. If the check fails, the card says it
couldn't check, with Try again. (Some clients reopen a card without its
earlier result. The card then starts again as a new card, with no memory of
the old one.)

A request that cannot be right (the same currency on both sides, a malformed
or unsupported currency code, or an amount that is zero, negative, too large
or has more than 2 decimal places) is refused before anything is sent, with
the reason.

`create_fx_quote`

Creates a real, short-lived exchange rate and holds the conversion ready.
The FX card's Get Quote button runs this — do not call it directly; start
with get_fx_quote. Only available on a client with interactive cards.

It moves no money, but it is a real action: every call prices a live quote.

How long a quote lasts is decided by whoever priced it, and it varies by
about five times between currency pairs — some expire in two minutes, some
in around ten. Go by the countdown on the card.

If a conversion from that card is already settled, or may still be going
through, no new quote is created and the card shows its status instead. If
you did not name the account to convert from, the company's own account in
the currency being sold is used when there is exactly one; with none or
several, the card appears without a Settle option.

Try asking

Convert 1,000 GBP to USD between our own accounts.

Then click Get Quote on the card. You do not ask for this tool by name.

`settle_fx_quote`

Submits the conversion. This moves real money between two of the
company's own accounts, once it has been approved in the Sokin portal.

Your Settle click on the FX card runs this, and it only settles the quote the
card showed you, unchanged. On a client that does not show cards it refuses
to run, before anything is sent, and points you to the Sokin portal.

Try asking

Convert 1,000 GBP to USD between our own accounts.

Then, once you have checked the rate on the card, click Settle. You do
not ask for this tool by name.

Settling hands back a receipt reference. get_instruction_request confirms
the conversion was created, and get_instruction shows where it stands,
however long ago it happened.

Things that stop a conversion, none of which send anything:

Anything different from the quote you reviewed.

A quote that has expired — you get the reason, and can ask for a fresh one.

A second attempt while the first is still going through.

If a conversion's outcome is genuinely unknown — a timeout, say — the tool
says exactly that rather than guessing, and tells you to check before
retrying. Submitting a conversion is also not the same as it happening: like a
payment, by default it waits for approval in the Sokin portal first. A quote lasts only
minutes, so it has often expired by the time someone approves. The portal will
not approve it at the old rate: the approver either rejects it (Rejected)
or takes a fresh rate, which closes this conversion as Failed with the reason
FX quote expired at approval. In that case, check the Sokin portal before
converting again: the approver may already have gone ahead at the new
rate.

`visualize`

Draws a diagram or renders rich text inside the chat. Needs a client with
interactive cards. Calls no Sokin service.

Most read tools have no card of their own, so this is how a result gets a
picture: the assistant reads the data, writes a diagram from it, and passes it
here.

Takes	Required	What it is
`markdown`	yes	Markdown to render. Code blocks tagged `mermaid` become diagrams
`title`	no	The card's heading

Try asking

Chart my account balances by currency.

The card is narrow, so top-to-bottom diagrams work better than
left-to-right, and small diagrams read best.

`get_documentation_links`

Hands back the web addresses of Sokin's own documentation, so an assistant can
read the real contract instead of guessing. Links only — never the content.
The answer comes from the server's own configuration, so it always matches
the server you are connected to.

Takes	Required	What it is
`topic`	no	`"b2b_api"`, `"mcp_server"`, or `"all"`. Default `"all"`

Try asking

Where is the documentation for Sokin's MCP server?

A topic with nothing published yet still gets a row, with the reason in place
of a link, rather than being left out.

It links the Sokin MCP documentation home on docs.sokin.com, which leads
to this page and the other two, and the Sokin B2B API reference, so an
assistant that asks for the documentation gets the real addresses. A server these pages do
not describe is left unconfigured on purpose — there the row
reads (none available) and says why, which is more useful than a link that
misdescribes what the client is connected to.

`play_cheetah_dash`

An endless-runner game, rendered in the chat. Takes nothing and calls no Sokin
service. Needs a client with interactive cards.

Try asking

Let's play Cheetah Dash.

Starter project ideas

All built on read-only tools — nothing moves money. Say the prompt in plain
English and let the client pick the tools.

Idea	Tools	Prompt to try
Multi-currency balance dashboard	`list_corporates`, `list_accounts`	"Build a dashboard of all my Sokin balances by currency, with a bar chart of the biggest five."
Payment tracker	`list_instructions`	"Build a page listing this week's payments and conversions, showing which are still waiting for approval."
Transaction history explorer	`get_account_ledger`	"Build a screen to pick an account and list its recent transactions, newest first, with a date filter."
Beneficiary directory	`list_beneficiaries`	"Create a searchable directory of my saved beneficiaries with currency and country."
Payment pre-flight checker	`validate_payment_instruction`	"Let me pick a saved payee, an account and an amount, and flag any problems without submitting anything."

The last one is the stretch, and it is still safe:
validate_payment_instruction saves nothing and moves no money.

Going deeper

Exact response schemas, field by field, every possible value of every
coded field, and the error and pagination contracts: Sokin MCP —
Technical Docs.

The Sokin B2B REST API underneath: https://docs.sokin.com, or
https://docs.sokin.com/llms.txt for the machine-readable index.

From inside a chat, ask for the documentation links and
get_documentation_links will return them.

Sokin MCP - Tool Guide

Jump to#

All 26 tools#

What you can ask for#

Reading a result#

Which tools your client can use#

Moving money#

The tools, one by one#

list_corporates#

list_accounts#

get_account#

get_account_ledger#

list_beneficiaries#

get_beneficiary#

get_beneficiary_schema#

validate_beneficiary#

create_beneficiary#

update_beneficiary#

list_financial_institutions#

list_financial_institution_branches#

list_instructions#

get_instruction#

get_instruction_request#

validate_payment_instruction#

create_payment_instruction#

submit_payment_instruction#

create_fx_payment_instruction#

submit_fx_payment_instruction#

get_fx_quote#

create_fx_quote#

settle_fx_quote#

visualize#

get_documentation_links#

play_cheetah_dash#

Starter project ideas#

Going deeper#

Jump to

All 26 tools

What you can ask for

Reading a result

Which tools your client can use

Moving money

The tools, one by one

`list_corporates`

`list_accounts`

`get_account`

`get_account_ledger`

`list_beneficiaries`

`get_beneficiary`

`get_beneficiary_schema`

`validate_beneficiary`

`create_beneficiary`

`update_beneficiary`

`list_financial_institutions`

`list_financial_institution_branches`

`list_instructions`

`get_instruction`

`get_instruction_request`

`validate_payment_instruction`

`create_payment_instruction`

`submit_payment_instruction`

`create_fx_payment_instruction`

`submit_fx_payment_instruction`

`get_fx_quote`

`create_fx_quote`

`settle_fx_quote`

`visualize`

`get_documentation_links`

`play_cheetah_dash`

Starter project ideas

Going deeper