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": {
    },
  • "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.