A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Wise API is how an app or AI agent moves money internationally: pricing a transfer with a quote, adding a recipient, creating and funding a transfer, and reading the currency balances in a multi-currency account. Access is granted through a Bearer API token, created as read-only or full-access with no finer-grained scopes, and money-moving actions like funding a transfer need a signed second factor on top. Wise versions each resource on its own and can push events to a registered webhook when a transfer changes state or a balance is credited.
How an app or AI agent connects to Wise determines what it can reach. There is a route for making calls with an API token, and a route for receiving events, and each is governed by the token behind it and the access level that token carries.
The REST API takes JSON request bodies and returns JSON, at https://api.wise.com, with a sandbox at https://api.sandbox.transferwise.tech. A call authenticates with a Bearer API token. Each resource is versioned independently in the path, like v1, v2, v3, or v4. Some money-moving and statement endpoints also require a signed second factor (Strong Customer Authentication) on top of the token in the UK and EEA.
Wise POSTs an event to a URL registered on a subscription when something happens, like a transfer changing state or a balance being credited. Subscriptions exist at the application level (across all profiles under an application) and at the profile level (one profile's resources). The receiver must respond with a 2xx status; any 3xx is treated as a delivery failure. Payloads can be verified against Wise's published public key.
A personal API token is sent as a Bearer token on every request. A token is created as either read-only or full-access for the account it belongs to; Wise does not offer granular per-endpoint scopes, so the access level is the whole permission model. The token reaches whatever the account behind it can see and do.
Wise Platform partners use OAuth 2.0 to connect customers' Wise accounts without handling their credentials. A client-credentials token authenticates the application itself, and a user access token, obtained through the authorization-code flow, acts for a specific user. Application-level calls use the former, profile-level calls the latter.
Money-moving and statement actions, like funding a transfer or pulling a statement in the UK and EEA, are not authorized by the token alone. The first request returns 403 with an x-2fa-approval one-time token; the integration signs that token with an RSA private key whose public key is registered on the account, then repeats the request with the x-2fa-approval and x-signature headers. One successful check opens a five-minute window where other calls skip it.
The Wise API is split into areas an agent can act on, like profiles, quotes, recipients, transfers, and balances. Each area has its own methods, and some methods, like funding a transfer, move real money and require a second factor on top of the token.
Methods for the personal or business identities that send and receive money.
Methods for the priced exchange-rate quote a transfer is built on.
Methods for the bank or account details money is sent to.
Methods for the payout order to a recipient, and funding it.
Methods for the currency balances inside a multi-currency account.
Methods for the subscriptions that deliver events to a URL.
Sandbox-only methods that drive a transfer through its states for testing.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ProfilesMethods for the personal or business identities that send and receive money.3 | ||||||
| GET | /v2/profiles | List the personal and business profiles belonging to the authenticated user. | read | Profiles read | Current | |
Read-only. A personal token reads whatever the account it belongs to can see. Acts onprofile Permission (capability) Profiles readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/profiles/{profileId} | Retrieve a single profile by its id. | read | Profiles read | Current | |
Read-only. Acts onprofile Permission (capability) Profiles readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/profiles | Create a personal or business profile under the account. | write | Profiles write | Current | |
Needs a full-access (read and write) token. Acts onprofile Permission (capability) Profiles writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
QuotesMethods for the priced exchange-rate quote a transfer is built on.4 | ||||||
| POST | /v3/profiles/{profileId}/quotes | Create an authenticated quote tied to a profile, the priced basis for a real transfer. | write | Quotes write | Current | |
Needs a user access token. Only an authenticated quote can back a real transfer. Acts onquote Permission (capability) Quotes writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/quotes | Create an unauthenticated quote for displaying a rate and estimate, not usable for a real transfer. | write | — | Current | |
No profile or auth needed; for display only, so it cannot create a transfer. Acts onquote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/profiles/{profileId}/quotes/{quoteId} | Retrieve a previously created quote by its id. | read | Quotes read | Current | |
Read-only. Acts onquote Permission (capability) Quotes readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/profiles/{profileId}/quotes/{quoteId} | Update a quote to attach the recipient account and a pay-in method once known. | write | Quotes write | Current | |
Sets targetAccount and payOut on an existing quote before the transfer is created. Acts onquote Permission (capability) Quotes writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Recipient accountsMethods for the bank or account details money is sent to.5 | ||||||
| POST | /v1/accounts | Create a recipient account, the bank or account details money is sent to. | write | Recipients write | Current | |
Required fields in the details object vary by currency and account type. Acts onaccount Permission (capability) Recipients writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts | List recipient accounts, optionally filtered by currency or profile. | read | Recipients read | Current | |
Read-only. Acts onaccount Permission (capability) Recipients readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/{accountId} | Retrieve a single recipient account by its id. | read | Recipients read | Current | |
Read-only. Acts onaccount Permission (capability) Recipients readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/accounts/{accountId} | Deactivate a recipient account so it can no longer be used. | write | Recipients write | Current | |
Deactivates rather than hard-deletes the recipient. Acts onaccount Permission (capability) Recipients writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/account-requirements | Return the fields required to create a valid recipient for a given quote and currency. | read | Recipients read | Current | |
Used to build the recipient form; it returns requirements, it does not create anything. Acts onaccount-requirement Permission (capability) Recipients readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TransfersMethods for the payout order to a recipient, and funding it.6 | ||||||
| POST | /v1/transfers | Create a transfer, a payout order to a recipient account based on a quote. | write | Transfers write | Current | |
Takes a quote id and a recipient account id. Creating a transfer does not move money; funding it does. A transfer usually must be funded within fourteen days. Acts ontransfer Permission (capability) Transfers writeVersionAvailable since the API’s base version Webhook event transfers#state-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/transfers/{transferId} | Retrieve a transfer by its id, including its current status. | read | Transfers read | Current | |
Read-only. Acts ontransfer Permission (capability) Transfers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/transfers | List transfers for a profile, filterable by status, currency, and date range. | read | Transfers read | Current | |
Read-only. Paged with offset and limit (up to 100 per page). Acts ontransfer Permission (capability) Transfers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/profiles/{profileId}/transfers/{transferId}/payments | Fund a transfer from a multi-currency balance, the step that actually sends the money. | write | Transfers write | Current | |
A high-risk action: it returns 403 first and must be repeated with a signed one-time token (Strong Customer Authentication) in the UK and EEA. Acts onpayment Permission (capability) Transfers writeVersionAvailable since the API’s base version Webhook event transfers#state-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/transfers/{transferId}/cancel | Cancel a transfer that has not yet been funded. | write | Transfers write | Current | |
Only unfunded transfers can be cancelled, and cancellation is final. Acts ontransfer Permission (capability) Transfers writeVersionAvailable since the API’s base version Webhook event transfers#state-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/delivery-estimates/{transferId} | Retrieve the current estimated arrival time for a transfer. | read | Transfers read | Current | |
Read-only. Acts ondelivery-estimate Permission (capability) Transfers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Balances & multi-currency accountMethods for the currency balances inside a multi-currency account.5 | ||||||
| GET | /v4/profiles/{profileId}/balances | List the balance accounts a profile holds inside its multi-currency account. | read | Balances read | Current | |
Read-only. A types query parameter is required, for example STANDARD. Replaces the deprecated v1 borderless-accounts endpoint. Acts onbalance Permission (capability) Balances readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/profiles/{profileId}/balances/{balanceId} | Retrieve a single balance account by its id. | read | Balances read | Current | |
Read-only. Acts onbalance Permission (capability) Balances readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/profiles/{profileId}/balances | Open a balance account in a chosen currency inside the multi-currency account. | write | Balances write | Current | |
Takes a currency and a type, for example STANDARD. Acts onbalance Permission (capability) Balances writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/profiles/{profileId}/balance-movements | Convert and move funds between two balance accounts in different currencies. | write | Balances write | Current | |
A cross-currency move needs a quote created with payOut set to BALANCE, and an X-idempotence-uuid header. Acts onbalance-movement Permission (capability) Balances writeVersionAvailable since the API’s base version Webhook event balances#creditRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/profiles/{profileId}/balance-statements/{balanceId}/statement.json | Generate a statement of the activity on a balance account over a date range. | read | Balances read | Current | |
A high-risk read in the UK and EEA, so it can return 403 and require the same signed one-time token as funding. Also available as CSV, PDF, and other formats. Acts onbalance-statement Permission (capability) Balances readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhook subscriptionsMethods for the subscriptions that deliver events to a URL.4 | ||||||
| POST | /v3/applications/{clientKey}/subscriptions | Create an application-level webhook subscription for an event type. | write | Webhooks write | Current | |
Application-level. Takes name, the event in trigger_on, the delivery URL, and a schema version. Most partners subscribe at this level. Acts onsubscription Permission (capability) Webhooks writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/profiles/{profileId}/subscriptions | Create a profile-level webhook subscription for events on one profile's resources. | write | Webhooks write | Current | |
Profile-level, authorized with a user token. Same body as the application-level subscription. Acts onsubscription Permission (capability) Webhooks writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/profiles/{profileId}/subscriptions | List the webhook subscriptions on a profile. | read | Webhooks read | Current | |
Read-only. Acts onsubscription Permission (capability) Webhooks readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/profiles/{profileId}/subscriptions/{subscriptionId} | Delete a profile-level webhook subscription so it stops delivering events. | write | Webhooks write | Current | |
Events already in flight are still delivered; no new events are sent after deletion. Acts onsubscription Permission (capability) Webhooks writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Simulation (sandbox)Sandbox-only methods that drive a transfer through its states for testing.2 | ||||||
| GET | /v1/simulation/transfers/{transferId}/{status} | Drive a sandbox transfer to a chosen state, like processing or outgoing_payment_sent, for testing. | write | — | Current | |
Sandbox only. States must be called in order: processing, funds_converted, outgoing_payment_sent, then optionally bounced_back or funds_refunded. Acts onsimulation Permission (capability)None required VersionAvailable since the API’s base version Webhook event transfers#state-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/simulation/balance/topup | Top up a sandbox balance so it can fund transfers or card spend during testing. | write | — | Current | |
Sandbox only. Returns a simulated successful top-up response. Acts onsimulation Permission (capability)None required VersionAvailable since the API’s base version Webhook event balances#creditRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Wise can notify an app when something happens in an account, like a transfer changing state or a balance being credited. It sends the event to a URL registered on a subscription, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
transfers#state-change | Fired every time a transfer's status changes, like moving to processing or outgoing_payment_sent. Top-up-to-balance transfers do not fire this; balances#update covers those. | /v1/transfers/v3/profiles/{profileId}/transfers/{transferId}/payments/v1/transfers/{transferId}/cancel/v1/simulation/transfers/{transferId}/{status} |
transfers#active-cases | Fired every time a transfer's list of active cases changes. Active cases flag potential problems holding up a transfer. | /v1/transfers |
balances#credit | Fired every time a multi-currency account balance is credited, for example when money arrives or a conversion settles. | /v2/profiles/{profileId}/balance-movements/v1/simulation/balance/topup |
balances#update | Fired when a balance changes, including the top-up-to-balance transfers that transfers#state-change does not cover. | /v2/profiles/{profileId}/balance-movements |
Wise limits how fast an app can call. Going over a limit returns a 429 response with a retry-after header that says how long to wait before trying again.
Wise meters requests by rate rather than by a per-method cost. Exceeding a limit returns HTTP 429 with a retry-after header that says how many seconds to wait before retrying. Wise does not publish a single fixed number for every endpoint, so an integration should respect the retry-after value and smooth its request rate. Writes that create money-moving resources should carry an idempotency key so a retry after a network blip does not create the resource twice.
List endpoints page with offset and limit query parameters. A transfer list returns up to 100 items per page, and an integration walks the pages by increasing offset until a short page is returned. Lists also accept filters such as status, currency, and a created-date range.
A transfer list returns at most 100 items per page (the maximum value of limit). A transfer usually has to be funded within fourteen days of being created, after which it expires. In the sandbox, simulation calls advance a transfer's state and should be spaced at least five seconds apart because processing is asynchronous.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | No valid token was supplied, or the token has expired. | Send a valid Bearer token, and refresh or reissue it if it has expired. |
| 403 | Forbidden / SCA required | The token lacks permission, or the action needs a second factor. A money-moving or statement call returns 403 with an x-2fa-approval header that names a one-time token to sign. | For a permission gap, use a full-access token. For a second-factor 403, sign the one-time token and repeat the request with the x-2fa-approval and x-signature headers. |
| 404 | Not Found | The requested resource does not exist, or is not visible to this token or profile. | Check the id, profile, and environment (sandbox versus production) match. |
| 422 | Validation error | The request was understood but failed validation. The body carries an errors array, each entry with code, message, path, and arguments. | Read each entry's path and message, fix the named fields, and resend. |
| 429 | Too Many Requests | The rate limit was exceeded. | Wait the number of seconds in the retry-after header, then retry with backoff. |
| 500 | Internal Server Error | An error on Wise's side. It is uncommon. | Retry idempotently with backoff, and contact Wise if it persists. |
Wise versions each part of its API independently in the path, like v1, v2, v3, or v4. Adding fields or resources does not change a version, while removing or renaming one mints a new version for the affected endpoints with at least six months of notice.
Wise does not publish a single global API version. Each resource is versioned independently in the path, so transfers and profiles sit at v1 while quotes are v3, recipient listing is v2, and balances are v4. Adding fields or resources is treated as non-breaking and does not change a version; removing or renaming one mints a new version for the affected endpoints. An old version is removed only with at least six months of notice.
The current balances API is served under /v4/profiles/{profileId}/balances for listing, retrieving, and creating balance accounts inside a multi-currency account. It supersedes the deprecated v1 borderless-accounts endpoint, which Wise directs integrations away from.
Through 2025 Wise published additive reference and endpoint changes across the API, including new KYC review and simulation endpoints, a formattedEstimatedDeliveryDate field on the delivery estimate, and newer versions of dispute-handling endpoints (a v4 upload dispute file endpoint and a v5 upload evidences endpoint).
Pin to the path versions an integration calls and move up when a newer one is published.
Wise API changelog ↗Bollard AI sits between a team's AI agents and Wise. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.