Authenticate by posting your API login ID and API key to the authenticate/api endpoint to obtain a session auth_token; include this token in the X-Auth-Token header on all subsequent requests
Get a conversion rate by calling the conversions/rates endpoint with the buy currency, sell currency, and amount; review the rate and settlement date before committing
Create the conversion by posting to the conversions/create endpoint with the agreed rate parameters; this locks the rate and debits your Currencycloud sell-currency balance; record the conversion_id
Create or retrieve a beneficiary via the beneficiaries/create endpoint with the recipient's bank details; validate the beneficiary using beneficiaries/validate before creating to catch field errors
Create a payment referencing the beneficiary_id and conversion_id; the payment moves the converted funds to the beneficiary; monitor payment status via the payments/get endpoint or webhooks for completed or failed status
Known gotchas
Currencycloud session auth_tokens expire after a period of inactivity; implement token refresh logic rather than re-authenticating on every request, and handle 401 responses by re-authenticating transparently
Conversions are binding once created; there is no cancel endpoint for a locked conversion — ensure your amount and currency pair are correct before posting to conversions/create
Beneficiary validation rules vary by currency corridor; a beneficiary valid for one currency may require additional fields (e.g., IBAN vs. account number + sort code) for another — always validate before creating
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp