logo
Documentation Powered by ReDoc

CurrencyFair eXternal Services API (2.0.0)

Download OpenAPI specification:Download

Customer Support: support@currencyfair.com

Introduction

The CurrencyFair eXternal Services API is REST-ful API that allows approved API users to perform various operations on their CurrencyFair wallet.

In order to use the API you will need to have a CurrencyFair account. You can sign up here.

It is designed to be used by server-side clients, to allow our business and institutional clients to build their own integrations with our system.

The production API server is https://xsapi.currencyfair.com

The sandbox servers are assigned to users when they register as an API partner.

The following headers can be attached to HTTPS calls to our API:

  • x-api-key: <secret provided by CurrencyFair> - must be sent in every request, grants access to the API (authentication is performed separately).
  • Authentication: Bearer <api_token> - must be set to authenticate the call. Read more in the Authentication section.
  • Content-Type: application/json - must be set on POST/PUT/PATCH calls when a JSON body payload is sent.
  • Accept-Language: <two_letter_language_code> - to set the language. Defaults to en if not provided. Currently supported languages: en, fr, de.

In order to use our API you need to first signup as our API partner. Please contact our customer service to arrange this.

Once you are our API partner, a new Sub User will be created under your company account. That Sub User will have its own long-lived Authorization Code that allows it to authenticate using the authentication endpoint.

api_key

A unique secret API Key (provided by CurrencyFair in advance) which must be sent with every request.

Security Scheme Type API Key
Header parameter name: x-api-key

Bearer

Retrieve/refresh a short-lived access token using a long-lived partner token.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: None, keys are assigned manually
Token URL: https://www.currencyfair.com/oauth
Refresh URL: https://www.currencyfair.com/oauth
Scopes:
  • xsapi -

    Authorized access

The Authorization Code must be stored in secure location, and never displayed to the public.

Sub Users can perform certain operations on behalf of their parent user, like Exchange, Transfer Out or Send Money. The scope of what a Sub User is allowed to do is controlled via the User Management panel in our web application.

In further text the term "user" will be used to described the currently authenticated Sub User.

Please read more about authentication process in the authentication endpoint description.

Error Responses

CurrencyFair follows the error response format proposed in RFC 7807 also known as Problem Details for HTTP APIs.

Basic error message

The base schema for all error responses is as follows:

type
required
string
title
required
string
status
required
integer

HTTP status code.

detail
required
string

Description of the error.

object

Optional object containing replacement values for errors with variables.

Example of not found entity.

{}

Error message with validation messages

Endpoints which receive a payload will perform validation of the input data, and return a HTTP 422 error response with validation_messages property.

The structure of the validation_messages is as follows:

{
  "<input_property_name>": {
    "<error_type>": "<error_message>",
    ...
  },
  ...
}

For example if an endpoints requires an iban field, which should be a valid IBAN number, and the provided value is not correct, the API will return an error like in the example below:

type
required
string
title
required
string
status
required
integer

HTTP status code.

detail
required
string

Description of the error.

object

Optional object containing replacement values for errors with variables.

validation_messages
object

Object holding validation messages.

Example of an endpoint returning validation messages.

{
  • "validation_messages": {
    },
  • "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  • "title": "Unprocessable Entity",
  • "status": 422,
  • "detail": "Could not add bank account"
}

Error message with failure messages

If the endpoint was unable to perform the requested operation, it may return a HTTP 4xx error response with failure_messages property.

The structure of the failure_messages is as follows:

{
  "<error_code>": "<error_message>",
  ...
}
type
required
string
title
required
string
status
required
integer

HTTP status code.

detail
required
string

Description of the error.

object

Optional object containing replacement values for errors with variables.

object

Array holding failure message (messageId => message).

Example of an endpoint returning failure messages

{}

MFA Required error message

This error is returned if an endpoint requires MFA to be performed prior to running it. Please see the MFA section for more details.

type
required
string
title
required
string
status
required
integer

HTTP status code.

detail
required
string

Description of the error.

required
object

Array of data required for MFA flow.

object

Optional object containing replacement values for errors with variables.

Example of POST endpoint returning 401 with MFA details.

{}

Rate limited error message

To ensure the CurrencyFair API remains stable to all users, CurrencyFair may throttle a client's requests if it deems the number of requests is excessive.

If this occurs, the API will return a 429 Too Many Requests response. Upon receiving a 429 response the client should resubmit failed requests using the the backoff approach, where your code performs a series of retries with increasing delays between each retry.

type
required
string
title
required
string
status
required
integer

HTTP status code.

detail
required
string

Description of the error.

object

Optional object containing replacement values for errors with variables.

{}

Multi Factor Authentication

In order to call Multi Factor Authentication (MFA) secured endpoints in our API, the client must have:

  • a secret MFA token
  • an MFA device ID

This information is provided as part of the API partner on-boarding process.

The MFA (aka 2FA) process in our API is as follows:

  • Client makes normal POST call to a MFA protected endpoint (it sends all the data like there is no MFA on the endpoint)
  • The API returns HTTP 401 with MFA details that include:
    • X-CF-MFA-FOLLOWON-ID:
  • Client uses its secret token for MFA authorization and performs calculation of the "MFA code"
  • Client repeats exactly the same POST call, but with these headers added:
    • X-CF-MFA-FOLLOWON-ID:
    • X-CF-MFA-DEVICE-ID:
    • X-CF-MFA-CODE:

This time the call will pass through the MFA layer and the endpoints will respond normally.

The MFA is valid for 15 minutes, so if you call the same endpoint again it may not ask for MFA verification.

Forms

Several of our endpoints are powered by a simple form fields system, where the POST endpoints receives a "form" that is defined by its "fields" endpoints.

Example:

GET /users/{userId}/namedDepositors/fields - returns a list of these "fields":

  • nameMessage - type: message
  • name - required, type: text
  • description - required, type: text

and the POST /users/{userId}/namedDepositors - sets up a named depositor, expects these fields:

  • name
  • description

This way of serving form fields is a UI-focused approach. It allows us to easily update forms in our applications according to business rules. The forms in our applications are rendered automatically based on the fields definitions.

For server-side API clients access, using a "fields" endpoint may not always be necessary. For example the Named Depositor fields are not likely to change and they don't depend on the user or any other parameters.

However certain endpoints like /countryAccountConfigs/{countryId} return a list of fields which differ based on the selected countryId.

The field definition object supports many more field types than those currently required for Named Depositors or setting up a User Account. It is used by our applications to render UI in other parts of the application, not covered by this API. However, it is likely that new features added to this API will use forms.

The full documentation for forms is available here: https://github.com/CurrencyFair/xsapi/blob/master/docs/Forms.md

Field definition

name
required
string (FieldName)

The name of the field.

type
required
string
Enum: "text" "textarea" "list" "checkbox" "image" "date" "file" "uploadedFile" "awaitingFile" "captcha" "message" "multiSelect"

The type of the field.

  • text: A text field
  • textarea: A textarea field
  • list: A list field
  • checkbox: A checkbox field
  • image: An image field to indicate an image is to be displayed
  • date: An date field
  • file: A file upload field
  • uploadedFile: Used as a banner indicating that the file is already uploaded
  • awaitingFile: Used as a banner indicating that a previous file is required to be uploaded
  • captcha: A captcha field
  • message: A message field
  • multiSelect: A multiSelect field
label
string

The label for the field.

required
boolean

Indicates if this field is required data.

tooltip
string

Text for a tool tip related to the field.

Array of objects (FieldValidator)
Array of objects (FieldFilter)
Array of objects (FieldMeta)

Holds additional information associated with the given input field.

{
  • "name": "firstname",
  • "type": "text",
  • "label": "Address Line 1",
  • "required": true,
  • "tooltip": "string",
  • "validators": [
    ],
  • "filters": [
    ],
  • "meta": [
    ]
}

Authentication

Authenticate

Successful authentication will produce an OauthResponse object which contains a token. The token must be then put into each next API call, into Authorization header, in the following way:

Bearer {token}

Example:

Authorization: Bearer 3d22ddea15b15e65909463ed821dc6c5
Authorizations:
api_key
header Parameters
x-api-key
required
string

The unique secret API Key which must be sent with every request.

Content-Type
required
string
Example: multipart/form-data

Indicates the type of data sent.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: multipart/form-data

The form values for authentication.

grant_type
required
string
Default: "authorization_code"

Type of authentication. Use authorization_code.

code
required
string

The long-lived secret token

client_id
required
string
Default: "xsapi"

Type of client. Use xsapi.

Responses

Request samples

Content type
multipart/form-data
{
  "grant_type": "authorization_code",
  "client_id": "xsapi",
  "code": "Wkmz8QBBP0Vwkp0wFuw3BUmoAZzeIORm9JpK1"
}

Response samples

Content type
application/json
{
  • "access_token": "3d22ddea15c24e65909463ec821dc6c5",
  • "refresh_token": "64a9d486030c4fb3bf52cdd3919eef9d635b0a335c804b45b0cba45ada22333f",
  • "expires_in": 1000,
  • "token_type": "Bearer",
  • "scope": null
}

Introduction to money operations

There are 3 basic operations in our system:

  • Deposit - In our UI, this is called "Top Up", "Transfer In" or "Request payment" which are all variants of depositing in money into your CurrencyFair wallet.
  • Exchange - Once money has been deposited, exchanging money in a user's currency wallet into another currency wallet.
  • Transfer Out - Once you have exchanged on the CurrencyFair platform, transferring money from CurrencyFair wallet into an external bank account.

A combination of these 3 operations (Deposit -> Exchange -> Transfer Out) is known technically as an Automatic Quick Trade or AQT. The customer facing description (shown in UI) is called a "Send Money" operation.

There are 2 ways the exchange operation can be made:

  • Quick Trade - this is an instant exchange with the rate CurrencyFair offers at a given moment.
  • Marketplace Trade - this is placing a trade "order", that gets "matched" when another customer places an order in an opposite currency pair for a similar value. It may take longer to happen, but a user can specify the desired exchange rate manually, and then wait for it to be matched.

Depositing

Depositing funds into a CurrencyFair account requires creating a deposit. There are multiple methods for creating a Deposit:

  1. Using a Named Depositor. This is the preferred method.
  2. Using an existing User Bank Account.
  3. By passing only a currency and amount, in which case a Recipient Bank Account will be created automatically.

Before creating a deposit you can determine the available payment methods for the deposit currency using the getPaymentMethodsWithTransferTimes endpoint.

In order to ensure seamless deposits, CurrencyFair requires that users include a reference in the reference field of the bank transfer. This reference usually consists of a user's CurrencyFair ID (CFID). To determine the exact reference required for a bank account refer to the the reference field returned from the getCurrencyfairAccount request.

There is no fee to deposit funds into CurrencyFair.

Create a Deposit

Creates a Deposit for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
required
object (SimpleAmountObject)

The monetary amount.

object (SimpleNamedDepositorObjectOrNull) Nullable
object (SimpleAccountObjectOrNull) Nullable
currency
string Nullable

The 3-characters currency code in ISO 4217 format. If the currency code is provided the account object is not required.

Responses

Request samples

Content type
application/json
Example
Create a Deposit with a Named Depositor.
Create a Deposit with a Named Depositor.
Create a Deposit with an Account.
{
  • "namedDepositor": {
    },
  • "amountInfo": {
    },
  • "currency": "EUR"
}

Response samples

Content type
application/hal+json

A typical Deposit Entity response.

{
  • "id": "781641",
  • "created": "2020-10-27T17:15:11+00:00",
  • "createdBy": null,
  • "cancelledBy": null,
  • "aqt": null,
  • "amountInfo": {
    },
  • "feeAmountInfo": {
    },
  • "nettAmountInfo": {
    },
  • "statusInfo": {
    },
  • "amount": 99.99,
  • "currencyCode": "EUR",
  • "_embedded": {
    }
}

Retrieve a list of Deposits

Retrieves a collection of Deposits for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

query Parameters
page
integer
Example: page=1

Page number in paginated collection.

page_size
integer [ 1 .. 100 ]
Default: 25
Example: page_size=25

Page size

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "page_count": 3,
  • "page_size": 25,
  • "total_items": 75,
  • "page": 1
}

Update a Deposit's values

Partially update a Deposit for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

id
required
string
Example: 123

The ID of the Deposit.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
required
object (SimpleStatusObject)

Responses

Request samples

Content type
application/json
{
  • "statusInfo": {
    }
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "createdBy": {
    },
  • "cancelledBy": {
    },
  • "statusInfo": {
    },
  • "amountInfo": {
    },
  • "feeAmountInfo": {
    },
  • "nettAmountInfo": {
    },
  • "_embedded": {
    }
}

Retrieve a Deposit

Retrieves a Deposit for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

id
required
string
Example: 123

The ID of the Deposit.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "createdBy": {
    },
  • "cancelledBy": {
    },
  • "statusInfo": {
    },
  • "amountInfo": {
    },
  • "feeAmountInfo": {
    },
  • "nettAmountInfo": {
    },
  • "_embedded": {
    }
}

Retrieve a list of CurrencyFair Bank Accounts

Retrieves a collection of CurrencyFair Bank Accounts.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "total_items": 2
}

Retrieve a CurrencyFair Bank Account

Retrieves a single CurrencyFair Bank Account by currency.

Authorizations:
api_keyBearer
path Parameters
currencyCode
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "accountId": "270750",
  • "accountName": "CurrencyFair Ltd",
  • "bankName": "AIB",
  • "bankAddress": [
    ],
  • "accountInformation": [
    ],
  • "message": "Euro standard transfers are made via the SEPA system within Europe.",
  • "reference": "CF4182220",
  • "_embedded": {
    }
}

Retrieve a Deposit Transaction Time

Retrieves a Deposit Transaction Times entity for a given Currency Code.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

currencyCode
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Deposit Transaction Time typical response.

{
  • "estimatedArrivalDate": {
    },
  • "_embedded": {
    }
}

Retrieve a list of Online Banks

Retrieves a collection of Online Banks.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Online Banks Collection

[
  • {
    }
]

Retrieve an Online Bank

Retrieves an Online Bank.

Authorizations:
api_keyBearer
path Parameters
id
required
integer

The Online Bank ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Online Banks entity

[
  • {
    }
]

Retrieves a list of Payment Methods for a provided currency

Retrieves a collection of Payment Methods for a provided currency. Each payment method will include an estimated transaction time.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

currencyCode
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

query Parameters
amount
integer
Example: amount=15000

The amount to be deposited.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Typical Payment Methods response.

{
  • "currencyCode": "EUR",
  • "_embedded": {
    }
}

Retrieves a list of Payment Methods for a provided currency corridor

Retrieves a collection of Payment Methods for a provided currency as well as transaction times relative to a second currency.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

currencyCode
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

transferCurrency
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

query Parameters
amount
string

The amount that will be deposited.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Typical Payment Methods response.

{
  • "currencyCode": "EUR",
  • "_embedded": {
    }
}

Named Depositors

A Named Depositor is a person or business transferring funds into your CurrencyFair wallet. The closer a Named Depositor name matches the actual bank account name, the greater chance of a quick and seamless deposit. If you are unsure, please use the person’s full name or the full company name.

Create a Named Depositor

A Named Depositor is a depositor which we identify by name when matching/clearing the deposit we receive. The more accurate this name is, the faster the money will be cleared to the user's wallet.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
name
required
string

The name associated with the Named Depositor.

description
string

A description associated with the Named Depositor.

Responses

Request samples

Content type
application/json
{
  • "name": "Max Mustermann",
  • "description": "A description of the Named Depositor."
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "customerId": 12345,
  • "name": "Max Mustermann",
  • "description": "A description relevant to the Named Depositor."
}

Retrieve a list of Named Depositors

Retrieves a collection of active Named Depositors for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "page_count": 3,
  • "page_size": 25,
  • "total_items": 75,
  • "page": 1
}

Retrieve a Named Depositor Fields Collection

Retrieves Named Depositor Fields required for adding/editing a named depositor.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "value": {
    }
}

Update a Named Depositor

Update a Named Depositor entity.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

id
required
integer
Example: 35833

The ID of the Named Depositor entity.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
name
required
string

The name associated with the Named Depositor.

description
string

A description associated with the Named Depositor.

Responses

Request samples

Content type
application/json
{
  • "name": "Max Mustermann",
  • "description": "A description of the Named Depositor."
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "customerId": 12345,
  • "name": "Max Mustermann",
  • "description": "A description relevant to the Named Depositor."
}

Retrieve a Named Depositor

Retrieves a Named Depositor entity.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

id
required
integer
Example: 35833

The ID of the Named Depositor entity.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "customerId": 12345,
  • "name": "Max Mustermann",
  • "description": "A description relevant to the Named Depositor."
}

Delete a Named Depositor

Deletes a Named Depositor entity.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

id
required
integer
Example: 35833

The ID of the Named Depositor entity.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/problem+json
{}

Quote and Exchange Money

Quote and Exchange Money endpoints are used to retrieve quotes and bank rate comparisons, as well as execute Quick Trade orders.

A Quick Trade refers to an instant currency exchange order. This differs to a Marketplace order, where the rate is configurable and the execution time of the order depends on how quickly your rate can be matched.

Retrieve a Comparison Quote

Retrieves a comparison of rates between CurrencyFair and a traditional bank for a BUY or SELL transfer between two provided currencies.

An example usage of this endpoint would be displaying a table comparing CurrencyFair's rates with a traditional bank's rates.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json

If no parameters are provided the call will return a SELL quote for €10,000 from EUR to GBP

currencyFrom
string (CurrencyFrom) [A-Z]{3}
Default: "EUR"

The SELL currency in ISO 4217 format.

currencyTo
string (CurrencyTo) [A-Z]{3}
Default: "GBP"

The BUY currency in ISO 4217 format.

type
string (QuoteType)
Enum: "BUY" "SELL"

The type of quote.

object (SimpleAmountObject)

The monetary amount.

ignoreFee
boolean

If the CurrencyFair fee should be ignored in calculations.

Responses

Request samples

Content type
application/json
{
  • "currencyFrom": "EUR",
  • "currencyTo": "GBP",
  • "type": "SELL",
  • "amountInfo": {
    },
  • "ignoreFee": false
}

Response samples

Content type
application/json
{
  • "currencyFrom": "EUR",
  • "currencyTo": "GBP",
  • "type": "SELL",
  • "amountInfo": {
    },
  • "savingsInfo": {
    },
  • "currencyFair": {
    },
  • "bank": {
    },
  • "totalSavings": {
    },
  • "smartRates": {
    },
  • "_embedded": {
    }
}

Return QuickTrade Quote

Returns a BUY or SELL quote for a transfer between two provided currencies

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
currencyFrom
string (CurrencyFrom) [A-Z]{3}
Default: "EUR"

The SELL currency in ISO 4217 format.

currencyTo
string (CurrencyTo) [A-Z]{3}
Default: "GBP"

The BUY currency in ISO 4217 format.

type
string (QuoteType)
Enum: "BUY" "SELL"

The type of quote.

amount
number <float>

The quote amount.

Responses

Request samples

Content type
application/json
{
  • "currencyFrom": "EUR",
  • "currencyTo": "GBP",
  • "type": "SELL",
  • "amount": 100
}

Response samples

Content type
application/json
{
  • "quote": {
    },
  • "rateInfo": {
    }
}

Create a QuickTrade Order

Create a BUY or SELL Quick Trade order for a provided amount of money and currency pair.

The request payload can be built using the response from POST /quicktradeQuote.

Please note that rates may fluctuate between receiving a quote and placing an order.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
required
object (QuickTradeQuotesQuoteObject)
required
object (RateInfoStandardInverseObject)

Information related to the standard and inverse rates.

Responses

Request samples

Content type
application/json
{
  • "quote": {
    },
  • "rateInfo": {
    }
}

Response samples

Content type
application/hal+json
{
  • "savingsInfo": {
    },
  • "_embedded": {
    }
}

Marketplace

The CurrencyFair Marketplace is where users can buy and sell currencies at a rate of their choosing. User's orders are matched with orders from other users.

Marketplace trades are only executed between trading hours. Information about a market's status and trading hours can be found in the responses of the getMarketplace and getMarketplaces requests.

Retrieve a list of User Orders

Retrieve a collection of Orders for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

query Parameters
page
integer
Example: page=1

Page number in paginated collection.

page_size
integer [ 1 .. 100 ]
Default: 25
Example: page_size=25

Page size

order_dir
string
Default: "desc"
Enum: "desc" "asc"

Ordering direction.

search
string

An Order ID to search for. If provided, the page parameter will be ignored, and the page on which the searched order exists will be returned.

status
integer
Enum: 3 7 8 9

The status ID by which to filter results. Both single and multiple (comma separated) values are accepted.

  • Order Unmatched: 7
  • Order Partially Matched: 8
  • Order Fully Matched: 9
  • Order Cancelled: 3
order_by
string
Default: "date"
Enum: "date" "type" "rate" "stats" "amountplaced" "amountto" "amountfrom" "progress"

The column on which to order results.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "page_count": 3,
  • "page_size": 25,
  • "total_items": 75,
  • "page": 1
}

Retrieve an Order

Retrieves an Order for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

orderId
required
integer
Example: 10

The Order ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "rateInfo": {
    },
  • "amountInfo": {
    },
  • "statusInfo": {
    },
  • "details": [
    ],
  • "isSmartRate": true,
  • "_embedded": {
    }
}

Update an open Order rate

Updates an open Order rate for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

orderId
required
integer
Example: 10

The Order ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
rate
required
number <float>

The new rate.

amount
required
number <float>

The remaining amount that the user wants to change rate for.

Responses

Request samples

Content type
application/json
{
  • "rate": 0,
  • "amount": 0
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "rateInfo": {
    },
  • "amountInfo": {
    },
  • "statusInfo": {
    },
  • "details": [
    ],
  • "isSmartRate": true,
  • "_embedded": {
    }
}

Cancel an Open Order

Cancels an Open Order for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

orderId
required
integer
Example: 10

The Order ID.

query Parameters
amount
required
number <float>
Example: amount=500.00

Verification of amount that should be cancelled.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/problem+json
{}

Retrieve Order History

Retrieves an Order's History for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

orderId
required
integer
Example: 10

The Order ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "tradeType": "MARKET_PLACE",
  • "tradeMode": "BUY",
  • "rateInfo": {
    },
  • "statusInfo": {
    },
  • "created": "2025-04-25T15:06:39+01:00",
  • "updated": "2025-04-25T15:06:39+01:00",
  • "events": [
    ],
  • "_embedded": {
    }
}

Retrieve Currency Marketplace Information

Returns currency exchange rates for all exchange markets.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "summary": "Example Marketplace collection response",
  • "_embedded": {
    },
  • "total_items": 18
}

Retrieve Marketplace information for a currency pair

Retrieves marketplace information for a provided currency pair.

Authorizations:
api_keyBearer
path Parameters
currencyFrom
required
string (CurrencyFrom) [A-Z]{3}
Default: "EUR"
Example: EUR

The SELL currency in ISO 4217 format.

currencyTo
required
string (CurrencyTo) [A-Z]{3}
Default: "GBP"
Example: GBP

The BUY currency in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "currencyFrom": "EUR",
  • "currencyTo": "GBP",
  • "incrementInfo": {
    },
  • "limitsInfo": {
    },
  • "status": "OPEN",
  • "marketStatusMetaData": {
    },
  • "items": [
    ]
}

Create Marketplace Order

Creates new marketplace order for provided amount of money, currency pair, trade-type and rate.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
currencyFrom
required
string (CurrencyFrom) [A-Z]{3}
Default: "EUR"

The SELL currency in ISO 4217 format.

currencyTo
required
string (CurrencyTo) [A-Z]{3}
Default: "GBP"

The BUY currency in ISO 4217 format.

type
required
string
Enum: "BUY" "SELL"

The type of order to executed.

amount
required
number <float>

The amount to be quoted.

rate
required
number <float>

The requested rate.

Responses

Request samples

Content type
application/json
{
  • "currencyFrom": "EUR",
  • "currencyTo": "GBP",
  • "type": "BUY",
  • "amount": 0,
  • "rate": 1.5
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "rateInfo": {
    },
  • "amountInfo": {
    },
  • "statusInfo": {
    },
  • "details": [
    ],
  • "isSmartRate": true,
  • "_embedded": {
    }
}

Recipient Bank Accounts

Recipient Bank Accounts are user created Bank Accounts which you can transfer money to.

Before creating a Recipient Bank Account you can fetch the required account information using the getCountryAccountConfig endpoint. The account information can be validated using the bankAccountLookup endpoint.

The requireBeneficiaryVerification endpoint can be used to determine if creating an account requires additional verification data.

Retrieve a Recipient Bank Account

Retrieve a Recipient Bank Account for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

accountId
required
integer
Example: 15

The Bank Account ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "accountId": "string",
  • "accountName": "Joe Bloggs Bank Account",
  • "bankName": "Bank of Ireland",
  • "bankAddress": [
    ],
  • "accountInformation": [
    ],
  • "additionalInformation": "string",
  • "createdByCustomer": {
    },
  • "beneficiaryAddress": "123 New Town Road, Dublin",
  • "beneficiaryCity": "Dublin",
  • "beneficiaryState": "Co. Dublin",
  • "beneficiaryPostCode": "A94VH77",
  • "beneficiaryEmail": "ben@example.com",
  • "beneficiaryEmailSend": true,
  • "accountNumber": "IE29AIBK93115212345678",
  • "accountNickname": "Joe Bloggs Account",
  • "_embedded": {
    }
}

Delete a Recipient Bank Account

Delete a Recipient Bank Account for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

accountId
required
integer
Example: 15

The Bank Account ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/problem+json
{}

Update a Recipient Bank Account's values

Partially update a Recipient Bank Account for a user.

Updating a Recipient Bank Account will generate a new accountId for the entity.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

accountId
required
integer
Example: 15

The Bank Account ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
accountNickname
required
string

The nickname associated with the account.

Responses

Request samples

Content type
application/json
{
  • "accountNickname": "Joe Bloggs Account"
}

Response samples

Content type
application/hal+json
{
  • "accountId": "string",
  • "accountName": "Joe Bloggs Bank Account",
  • "bankName": "Bank of Ireland",
  • "bankAddress": [
    ],
  • "accountInformation": [
    ],
  • "additionalInformation": "string",
  • "createdByCustomer": {
    },
  • "beneficiaryAddress": "123 New Town Road, Dublin",
  • "beneficiaryCity": "Dublin",
  • "beneficiaryState": "Co. Dublin",
  • "beneficiaryPostCode": "A94VH77",
  • "beneficiaryEmail": "ben@example.com",
  • "beneficiaryEmailSend": true,
  • "accountNumber": "IE29AIBK93115212345678",
  • "accountNickname": "Joe Bloggs Account",
  • "_embedded": {
    }
}

Validate the Recipient Bank Account can be used for transfer or deposit

Validates that a Recipient Bank Account's information is valid for the creation of a transfer or deposit.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

accountId
required
integer
Example: 15

The Bank Account ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

Retrieve a list of Recipient Bank Accounts

Retrieves a collection of Recipient Bank Accounts for user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "total_items": 0
}

Create a Recipient Bank Account

Creates a Recipient Bank Account for a user. You must call this endpoint twice - first to get MFA followon id, and again with the MFA code in the header. Both call's parameters must be identical. Please refer to the MFA documentation.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

x-cf-mfa-followon-id
string

The MFA followon ID.

x-cf-mfa-device-id
string

The MFA device ID.

x-cf-mfa-code
string

The MFA code.

Request Body schema: application/json

New account data

accountName
required
string

The name associated with the account.

bankName
required
string

The bank name.

bankAddress
required
Array of strings

The bank address.

required
Array of objects (AccountInformationSimplified)

Array of account details. Required fields depend on thecountry and currency. Use GET /countryAccountConfigs endpoint to retrieve the required account number fields. You must add the following details if the account is in theUSA and in USD currency: beneficiaryAddress, beneficiaryCity, beneficiaryState, beneficiaryPostCode, beneficiaryCountryOfResidence'

required
object (CurrenciesEntitySimplified)
required
object (CountriesEntitySimplified)
additionalInformation
string

Additional information associated with the bank account.

beneficiaryVerification
object

Verification information related to a beneficiary. For example if the beneficiary has accepted the BullionVault terms.

Responses

Request samples

Content type
application/json
Example
iban-swift
iban-swift
us-account

Creating an IBAN/Swift Bank Account.

{
  • "bankName": "COMMERZBANK AG",
  • "accountName": "Joe Bloggs",
  • "country": {
    },
  • "accountInformation": [
    ],
  • "currency": {
    },
  • "bankAddress": [
    ]
}

Response samples

Content type
application/hal+json
{
  • "accountId": "string",
  • "accountName": "Joe Bloggs Bank Account",
  • "bankName": "Bank of Ireland",
  • "bankAddress": [
    ],
  • "accountInformation": [
    ],
  • "additionalInformation": "string",
  • "createdByCustomer": {
    },
  • "beneficiaryAddress": "123 New Town Road, Dublin",
  • "beneficiaryCity": "Dublin",
  • "beneficiaryState": "Co. Dublin",
  • "beneficiaryPostCode": "A94VH77",
  • "beneficiaryEmail": "ben@example.com",
  • "beneficiaryEmailSend": true,
  • "accountNumber": "IE29AIBK93115212345678",
  • "accountNickname": "Joe Bloggs Account",
  • "_embedded": {
    }
}

Recipient Bank Account configuration per Country

Retrieves all the Bank Account field configuration for a given country and its allowed currencies. This field configuration should be used when determining which fields are needed to add a Bank Account. An optional currency querystring param can be used to filter results by (if not provided, results will show all allowed currencies for the CountryId).

Authorizations:
api_keyBearer
path Parameters
countryId
required
integer
Example: 15

The ID of the Country entity. See getCountries.

query Parameters
currency
string[A-Z]{3}
Example: currency=EUR

The 3 character currency code in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "value": {
    }
}

Retrieve Bank Details for provided Account details

Retrieves Bank Details from provided Bank Account information and Country ID. Returns an error response for invalid bank details.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Content-Type
required
string
Example: multipart/form-data

Indicates the type of data sent.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
required
object (CountriesEntitySimplified)
required
Array of objects (AccountInformation)

An array of account information to validate

Responses

Request samples

Content type
application/json
Example
Irish IBAN Bank Account payload
Irish IBAN Bank Account payload
USA Account payload
Honk Kong Account payload
{
  • "accountInformation": [
    ],
  • "country": {
    }
}

Response samples

Content type
application/json
Example
Irish IBAN Bank Account response
Irish IBAN Bank Account response
USA Account response
Honk Kong Account response
[
  • {
    },
  • {
    },
  • {
    }
]

Retrieve a Beneficiary verification status

Determines if a Beneficiary is a BullionVault account and requires verification.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
iban
string

The IBAN number. If provided, accountNumber and sortCode are not required.

accountNumber
integer

The Account Number. Required if IBAN is not provided.

sortCode
integer

The Account Sort Code. Required if IBAN is not provided.

object (CountriesEntitySimplified)

Responses

Request samples

Content type
application/json
{
  • "iban": "IE25HDRD73367504201086",
  • "accountNumber": 21301283,
  • "sortCode": 931365,
  • "country": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve an object containing the fields required for customer activation based on the country of registration

Authorizations:
api_keyBearer
path Parameters
countryId
required
integer

country ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "countryId": 15,
  • "fields": [
    ]
}

Transfer Out

Transfer Out is the process of sending money from a customer's CurrencyFair wallet to a Recipient.

Create a Transfer Out

Creates a new Transfer Out of the money from a customer's wallet into a Bank Account.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json

A Transfer Out entity

required
object
required
object
required
object
required
object
required
object
required
object
customTransferPurpose
required
string Nullable

If the selected transfer purpose is of type Other, this field takes the value of customer-entered purpose reason.

beneficiaryEmailSend
boolean Nullable

Whether to notify the beneficiary of the transfer via email.

beneficiaryEmail
string Nullable

The email of the beneficiary. Required if beneficiaryEmailSend is true.

Responses

Request samples

Content type
application/json
Example
Typical Transfer Out
Typical Transfer Out
Complicated Transfer Out

This is a minimal object required to create a transfer.

{
  • "account": {
    },
  • "amountInfo": {
    },
  • "transferType": {
    },
  • "feeInfo": {
    },
  • "references": {
    },
  • "purpose": {
    },
  • "customTransferPurpose": null,
  • "beneficiaryEmailSend": null,
  • "beneficiaryEmail": null
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "createdBy": {
    },
  • "cancelledBy": {
    },
  • "references": {
    },
  • "amountInfo": {
    },
  • "feeInfo": {
    },
  • "statusInfo": {
    },
  • "customTransferPurpose": "Sending money to my friend",
  • "estimatedArrivalDate": {
    },
  • "detailsStatusInfo": {
    },
  • "_embedded": {
    }
}

Retrieve a list Transfer Outs

Retrieves a collection of Transfer Out entities for a user, paginated to 25 results per page. Transfers are sorted by the time of creation and returned in descending order.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

query Parameters
page
integer
Example: page=1

Page number in paginated collection.

status
integer (TransferStatusEnum)
Enum: 2 3 6 10

Filter transfers by status code. Possible values:

  • Confirmed: 2
  • Cancelled: 3
  • Pending: 6
  • Returned: 10
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "value": {
    }
}

Retrieve a Transfer Out

Retrieves a single Transfer Out for a user

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

transferId
required
integer
Example: 12345

The ID of transfer.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
Example
Confirmed Transfer Out
Confirmed Transfer Out
Pending Transfer Out

This is how a typical Transfer Out looks like for a customer.

{
  • "id": "107025009",
  • "created": "2020-10-19T13:47:52+01:00",
  • "createdBy": {
    },
  • "cancelledBy": null,
  • "aqt": null,
  • "references": {
    },
  • "amountInfo": {
    },
  • "feeInfo": null,
  • "statusInfo": {
    },
  • "customTransferPurpose": null,
  • "estimatedArrivalDate": null,
  • "_embedded": {
    }
}

Update an existing Transfer

Partially update the Transfer Out for a user. Allows updating the statusInfo.status property, to approve a pending transfer. Only allowed if the logged in customer has the capability to approve transfers.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

transferId
required
integer
Example: 12345

The ID of transfer.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json

A partial Transfer Out entity.

required
object

Responses

Request samples

Content type
application/json
Example
Confirmed Transfer Out
Confirmed Transfer Out
Cancelled Transfer Out

The Transfer Out created by a SubUser and confirmed by another user with capability to do so

{
  • "id": "107025009",
  • "created": "2020-10-19T13:47:52+01:00",
  • "createdBy": {
    },
  • "cancelledBy": null,
  • "aqt": null,
  • "references": {
    },
  • "amountInfo": {
    },
  • "feeInfo": null,
  • "statusInfo": {
    },
  • "customTransferPurpose": null,
  • "estimatedArrivalDate": null,
  • "_embedded": {
    }
}

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "created": "2025-04-25T15:06:39+01:00",
  • "createdBy": {
    },
  • "cancelledBy": {
    },
  • "references": {
    },
  • "amountInfo": {
    },
  • "feeInfo": {
    },
  • "statusInfo": {
    },
  • "customTransferPurpose": "Sending money to my friend",
  • "estimatedArrivalDate": {
    },
  • "detailsStatusInfo": {
    },
  • "_embedded": {
    }
}

Retrieve a list of Transfer Types

Retrieves a collection of Transfer Types.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
[
  • {
    }
]

Retrieve a list of Transfer Purposes

Retrieves a collection of Transfer Purposes.

Authorizations:
api_keyBearer
query Parameters
currencyCode
string[A-Z]{3}
Example: currencyCode=EUR

The 3 character currency code in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
Example
Transfer Purposes collection
Transfer Purposes collection
Transfer Purposes collection for specific currency
[
  • {
    }
]

Retrieve a list of Transfer Fees

Retrieves a collection of Transfer Fees.

Authorizations:
api_keyBearer
query Parameters
excludeFreeTransfer
integer
Default: 0
Enum: 0 1

Use value 1 to ignore Free Transfers.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
[
  • {
    }
]

Retrieve a list of Free Transfer Reward details for a user

Retrieves a collection of Free Transfer Reward details for a user.

These are the full details of the individual Free Transfer Rewards for both priority and standard transfers, both available and already used or expired.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Free Transfer Rewards collection

[
  • {
    }
]

Transfer Approvals

Retrieve a list of Transfer Approvers

Retrieves collection of Transfer Approvers

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

transferId
required
integer
Example: 12345

The ID of transfer.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "total_items": 2
}

Send notifications to Transfer Approvers

Sends notifications to Transfer Approvers.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

transferId
required
integer
Example: 12345

The ID of transfer.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json

Collection of transfer approvers to notify.

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "approvers": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Send Money

Send money, or Automatic Quick Trade, refers to the combined action of depositing, exchanging and transferring funds to a beneficiary. Further information on how Send Money operates can be found here.

Create an Automatic Quick Trade

Creates an Automatic Quick Trade for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Request Body schema: application/json
required
object (QuickTradeQuotesEntity)
required
object (DepositsEntitySimplified)
required
object (TransfersEntitySimplified)

Responses

Request samples

Content type
application/json

An example Automatic Quick Trade payload.

{
  • "order": {
    },
  • "transfer": {
    }
}

Response samples

Content type
application/hal+json

An example Automatic Quick Trade response.

{
  • "id": "983718",
  • "created": "2020-10-27T16:12:26+00:00",
  • "deposit": {
    },
  • "order": null,
  • "transfer": null,
  • "estimatedArrivalDate": {
    },
  • "_embedded": {
    }
}

Retrieve a list of Automatic Quick Trades

Retrieves a collection of Automatic Quick Trades for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

query Parameters
status
string
Example: status=1,2,4

Optional statuses to filter by. Accepts single or multiple in CSV format

ACTIVE - 0

COMPLETED - 1

EXPIRED - 2

CANCELLED - 3

FAILED - 4

SUSPENDED - 5

SUSPENDED_AWAITING_DOCS - 6

SUSPENDED_AML_VERIFICATION - 7

PROCESSING - 8

PENDING_MARKET_OPENING - 9

SUSPENDED_AWAITING_BENE_INFO - 10

PENDING_EXCHANGE_NOT_AVAILABLE - 11

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    }
}

Retrieve a list of Automatic Quick Trade Statuses

Retrieves a collection of Automatic Quick Trade Statuses for a user.

Authorizations:
api_keyBearer
query Parameters
filter
string
Value: "open"

An optional filter. Currently accepts open which returns open / in progress Automatic Quick Trade Statuses.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Typical Automatic Quick Trade Statuses response.

{
  • "_embedded": {
    },
  • "total_items": 11
}

Retrieve an Automatic Quick Trade Status

Retrieves an Automatic Quick Trade Status for a user.

Authorizations:
api_keyBearer
path Parameters
statusId
required
integer
Example: 123

The Automatic Quick Trade Status ID.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Typical Automatic Quick Trade Statuses entity response.

{
  • "id": 1,
  • "label": "Completed",
  • "description": "A completed automatic quick trade"
}

Retrieve an Automatic Quick Trade

Retrieves an Automatic Quick Trade for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

id
required
string
Example: 123

The ID of the Automatic Quick Trade.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": 0,
  • "deposit": {
    },
  • "created": "2025-04-25T15:06:39+01:00",
  • "estimatedArrivalDate": {
    },
  • "_embedded": {
    }
}

Retrieve a Combined Transaction Time (Deposit + Transfer)

Retrieves a Combined Transaction Time entity consisting of Deposit and Transfer transaction times.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

fromCurrencyCode
required
string
Example: EUR

The 3 character currency code ISO 4217 format.

transferType
required
string
Enum: "STANDARD" "PRIORITY"

The Transfer Type. Priority should only be used with the ILS currency.

toCurrencyCode
required
string
Example: GBP

The 3 character currency code ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Combined Transaction Time typical response.

{
  • "estimatedArrivalDate": {
    },
  • "_embedded": {
    }
}

Countries & Currencies

These endpoints provide information related to countries and currencies, and what level of support CurrencyFair provides for each. For example, you can query these endpoints to determine a default currency for a country, or to see if CurrencyFair allows registration for a particular country.

Retrieve a list of Countries

Retrieves the full list of countries that CurrencyFair supports. Support for a country does not imply registration capabilities, or deposit/transfer capabilities.

Authorizations:
api_keyBearer
query Parameters
currencyCode
string[A-Z]{3}
Example: currencyCode=EUR

The 3 character currency code in ISO 4217 format.

account
integer
Default: 0
Enum: 0 1

Use value 1 to get the list of Countries filtered by those which allow the setting up of a Bank Account.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "total_items": 2
}

Retrieve a Country

Retrieves a Country.

Authorizations:
api_keyBearer
path Parameters
id
required
integer (IdParam)
Example: 15

Country ID

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": "15",
  • "countryCode": "IE",
  • "name": "Ireland",
  • "dialCode": "353",
  • "allowsRegistration": true,
  • "registrationMessage": null,
  • "_embedded": {
    }
}

Retrieve a list of Currencies

Retrieves a collection of Currencies.

Authorizations:
api_keyBearer
query Parameters
include_disabled
integer

Use value 1 to retrieve a list of all currencies, including those which are disabled.

cf_client_account
integer

Use value 1 to retrieve a list of currencies for which a CurrencyFair Bank Account exists and that we accept deposits in.

account
integer

Use value 1 to retrieve a list of currencies that can be used with a user Bank Account.

regional_entity
string
Example: regional_entity=Singapore

Use value 1 to retrieve a list of currencies for the supplied regional entity.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "_embedded": {
    },
  • "total_items": 2
}

Retrieve a Currency

Retrieves a Currency.

Authorizations:
api_keyBearer
path Parameters
currencyCode
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "currencyCode": "EUR",
  • "description": "Euro",
  • "minDeposit": 8,
  • "maxDeposit": 10000000,
  • "minimumSellAmount": 5,
  • "marketplaceEnabled": true,
  • "aqtOnly": false,
  • "buyOnly": false,
  • "acceptDeposits": true,
  • "roundingScale": 2,
  • "targetCurrencies": [
    ]
}

User Information

These endpoints provide generic, user-specific information.

Who Am I

Retrieves basic information about the logged in user.

Authorizations:
api_keyBearer
header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/json

Whoami Entity

{
  • "id": 578225,
  • "customerCode": "CF5578225",
  • "firstname": "John",
  • "surname": "Doe",
  • "email": "john.doe@example.com",
  • "isTrial": false,
  • "isActive": true,
  • "signupDate": "2020-03-31 13:41:24"
}

Retrieve a User

Retrieves a User associated with a provided User ID.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
{
  • "id": 15,
  • "salutation": "Mr.",
  • "firstname": "John",
  • "middleName": "string",
  • "surname": "Doe",
  • "dateOfBirth": "1977-11-11T00:00:00.000Z",
  • "email": "john.doe@example.com",
  • "address1": "12 Main Street",
  • "address2": "string",
  • "address3": "string",
  • "city": "Dublin",
  • "postCode": "D01",
  • "isCompany": true,
  • "regionalEntity": "Ireland",
  • "isSubUser": true,
  • "_embedded": {
    }
}

Retrieve a list of Summaries

Retrieves a collection of Summaries for a user. Each summary is associated with a currency and contains information such available funds, pending deposits and open orders.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
[
  • {
    }
]

Retrieve a Summary

Retrieves a Summary of a information related to a provided Currency for a User. A summary contains information such available funds, pending deposits and open orders for a currency.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

currencyCode
required
string[A-Z]{3}
Example: EUR

The 3 character currency code in ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json

Summaries entity

[
  • {
    }
]

Retrieve a list of Wallet Transactions

Retrieves a collection of Wallet Transactions for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

query Parameters
context
required
string
Value: "statement"

The context in which transactions are returned - currently only 'statement'.

currency
required
string
Example: currency=EUR

Currency filter. ISO 4217 format.

start_date
required
string <date-time>
Example: start_date=2020-09-01T13:47:52+01:00

Start date filter in ISO 8601 format. If provided in short form (date-only), the starting time of 00:00:00 (Dublin timezone) is assumed.

end_date
required
string <date-time>
Example: end_date=2020-09-10T13:47:52+01:00

End date filter in ISO 8601 format. If provided in short form (date-only), the ending time of 23:59:59 (Dublin timezone) is assumed.

page
integer
Example: page=1

Page number in paginated collection.

page_size
integer [ 1 .. 100 ]
Default: 25
Example: page_size=25

Page size

order_by
string
Default: "timestamp"
Value: "timestamp"

Property name to order by. Currently only timestamp.

order_dir
string
Default: "desc"
Enum: "desc" "asc"

Ordering direction.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
Example
Wallet Transactions collection
Wallet Transactions collection
Empty Wallet Transactions collection
[
  • {
    }
]

Retrieve a Wallet Transaction

Retrieves a Wallet Transaction for a user.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

transactionId
required
integer

The ID of the Wallet Transaction.

query Parameters
context
required
string
Value: "statement"

The context in which transactions are returned - currently only 'statement'.

currency
required
string
Example: currency=EUR

Currency filter. ISO 4217 format.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples

Content type
application/hal+json
[
  • {
    }
]

Export a list of Wallet Transactions

Trigger an export of Wallet Transactions collection into a file.

Authorizations:
api_keyBearer
path Parameters
userId
required
integer
Example: 12345

The Customer ID for the logged in User.

query Parameters
format
required
string
Enum: "csv" "pdf" "csv_xero" "csv_split"

Format of the exported file.

context
required
string
Value: "statement"

The context in which transactions are returned - currently only 'statement'.

currency
required
string
Example: currency=EUR

Currency filter. ISO 4217 format.

start_date
required
string <date-time>
Example: start_date=2020-09-01T13:47:52+01:00

Start date filter in ISO 8601 format. If provided in short form (date-only), the starting time of 00:00:00 (Dublin timezone) is assumed.

end_date
required
string <date-time>
Example: end_date=2020-09-10T13:47:52+01:00

End date filter in ISO 8601 format. If provided in short form (date-only), the ending time of 23:59:59 (Dublin timezone) is assumed.

page
integer
Example: page=1

Page number in paginated collection.

page_size
integer [ 1 .. 100 ]
Default: 25
Example: page_size=25

Page size

order_by
string
Default: "timestamp"

Property name to order by.

order_dir
string
Default: "desc"
Enum: "desc" "asc"

Ordering direction.

header Parameters
Authorization
required
string

The client must send this token in the Authorization header when making requests to protected resources.

x-api-key
required
string

The unique secret API Key which must be sent with every request.

Accept-Language
string
Example: en

Indicates the preferred locale variant.

Responses

Response samples