FTX Whitelabel User Docs – FTX Exchange

Whitelabeling FTx

More or less everything that you can do with FTX can be done via API. This means that it's easy to build FTX into your products!

This article gives an overview of how to add FTX functionality to your product suite; please reach out if you're interested.

Whitelabel API Documentation

This document contains information about user management for your whitelabel. Everything else can be found in our standard API docs: https://docs.ftx.com/

For the 2FA section, please try to emulate what the FTX website does.

Let us know if you have any questions!

Creating and authenticating as users

In your application, to make an authenticated request on behalf of a user, you should supply the following request headers:

Subaccount

If omitted, we will assume you are trying to access the main account

Authorization: Bearer {token}

Note that this fully replaces the purpose and use of user API keys in your application. All endpoints that APIs can access can be used the same way with an auth token with just a change in the request headers! So the existing API docs should still be correct: https://docs.ftx.com/

Create user

Notes:

This will attempt to create a fresh user with that email/password if one doesn’t exist with that email yet.
This is one of two endpoints that authenticates using a key corresponding to your master account. The rest all follow the authentication scheme described above.
This endpoint will be rate limited and monitored for abnormal access patterns
The token returned will have the same privileges as the token given from Fetch initial user token

POST https://ftx.com/api/users/whitelabel/create

Params:

email: string
password: string
referralCode: string or int

Returns:

token: str

Fetch initial user token

Notes:

This is the other endpoint that authenticates using a key corresponding to your master account. The rest all follow the authentication scheme described above.
This endpoint returns a token that gives you full access to the account if the account doesn’t have 2FA set up. If it does, you will have to make a request to /login_with_mfa using this token to get a new token

POST https://ftx.com/api/users/whitelabel/login user token

Params:

email: string
password: string

Returns:

token: str

Get user information

Notes:

This endpoint is mostly here for you to use to double check the status of your auth token

For endpoints that are authenticated using a user auth token, supply the following in the request header for authentication:

Authorization: Bearer {token}

The relevant fields here are loggedIn (which will be False if you don’t have access to the account) and mfaRequired.
If you are using a valid auth token supplied by the Fetch user token endpoint but see loggedIn = False, check if mfaRequired exists. It will tell you what type of 2FA you need to supply to get a more functional auth token for this account.
If loggedIn is True, then you should be set.

GET https://ftx.com/api/login_status

Returns:

loggedIn: bool
account: dict -- an account representation, like here
subaccount: dict

nickname

user: dict -- below are some of the important fields

kycLevel: int

Explained further in the KYC section below

kycApplicationStatus: str

Explained further in the KYC section below

displayName: str
email: str
referrerId: int
vip: bool
feeTier: int

mfaRequired: bool

Login with MFA

POST https://ftx.com/api/login_with_mfa

Notes:

You’ll want to use an auth token that gives you partial authentication (ones for which queries to /login_stauts give you results with mfaRequired set to something not null and loggedIn set to False). This endpoint will return an auth token that gives you full access to the account
The code should be retrieved using the user’s 2FA method. If TOTP, can just ask them to supply what their TOTP app says. If SMS, you will have to prompt FTX to text them once (using the /sms/request endpoint below) and then ask them to supply the texted code.

Params:

code: str

Returns:

token: str

Log out

POST https://ftx.com/api/logout

Notes:

This invalidates the auth token used to make this request

Handling and Setup of 2FA

Everything in this section will operate on the user corresponding to the supplied auth token. Note that this auth token must have full permissions -- i.e. requests made to /login_status with it should have loggedIn: true.

There are two forms of supported 2FA: SMS and TOTP. They have two different auth flows.

Note that in order to fetch deposit addresses or withdrawal addresses for a user, that user must have 2FA set up.

SMS

SMS 2FA Setup

POST https://ftx.com/api/mfa/sms/setup

Notes:

This endpoint sends a text message with a code to the supplied phone number
The expected format for phoneNumber is +{countryCode}{fullySpecifiedPhoneNumber}

E.g. “+79990101156” or “+14086210191”

This endpoint requires that the user is fully authenticated. So it should not be used for sending a text message to a user when trying to authenticate their login with /login_with_mfa.

Params:

phoneNumber: str

Establish SMS MFA

POST https://ftx.com/api/sms/setup/verify

Notes:

This endpoint establishes SMS 2FA for the user and returns you a new authenticated token corresponding to that user if it is successful
You should send the `phoneNumber` that was used from the previous step (SMS 2FA Setup). The `code` should be supplied by the user, copying what we texted them.
If they are switching from a previous 2FA setup, supply the code corresponding to that

If their previous 2FA setup used SMS, you will need to prompt sending them a text with a code using the /sms/setup endpoint (see below)
If their previous 2FA setup was TOTP, they can just supply it using what their app currently shows them

Params:

phoneNumber: str
code: str
existingCode: str

Request SMS

POST https://ftx.com/api/mfa/sms/request

Notes:

This endpoint DOES NOT require that the user is fully authenticated. Can use a partially authenticated token (like one whose /login_status result gives mfaRequred set to ‘sms’ and loggedIn set to ‘false)
Sends a text to the user with a code
Fails if the user does not have SMS 2FA set up or if sending the code via SMS fails

TOTP

Generate TOTP seed

Notes:

This returns a randomly generated TOTP seed. Show this to your user, represented in a QR code and in raw text, to put inside the TOTP app of their choice (Google Authenticator, 1Password, Authy, etc)

POST https://ftx.com/api/mfa/generate_totp_seed

Set TOTP MFA

Notes:

This endpoint establishes 2FA for the user and returns you a new authenticated token corresponding to that user if it is successful
You should send the `seed` that was returned from the previous step (Generate TOTP seed). The `code` should be what the user supplied when you prompt them for what their app shows them when using the seed.
If they are switching from a previous 2FA setup, supply the code corresponding to that

If their previous 2FA setup used SMS, you will need to prompt sending them a text with a code using the /sms/setup endpoint
If their previous 2FA setup was TOTP, they can just supply it using what their app currently shows them

POST https://ftx.com/api/mfa/set_totp_mfa

Params:

code: str
seed: str
existingCode: optional str

Returns:

token: str

User KYC

Higher KYC levels grant users the ability to trade FTT and higher withdrawal limits.

You can use the kycApplicationStatus and kycStatus fields from /login_status to track a user’s application status.

These below endpoints are used to submit KYC applications.

Tracking KYC

See the /login_status endpoint above for information on KYC. Here is how to interpret the KYC-related fields in `user` dict that is returned when using a fully authenticated token

kycLevel: int

See here for a description of what the different levels grant https://help.ftx.com/hc/en-us/articles/360027668192-Individual-Account-KYC
Users start out at kycLevel 0

kycApplicationStatus

Either not_started, submitted, rejected, or action_needed
This application status always corresponds to the level above their current kycLevel, except for rejected: rejected means that they are rejected from FTX altogether
This means that users start out with kycApplicationStatus ‘not_started’

Submitting Level 1 KYC

POST https://ftx.com/api/kyc/level_1

Form Data:

country: str

three-letter Alpha2 country letter code
Display ”Country of residency”

fullLegalName: str

Their full legal name (first, middle, last)

fullLegalNameEnglish: str

If from Korea, Ukraine, or Russia, or using non-latin characters

stateProvinceRegion: str

The state, region, or province they reside in

noCriminalRecordDeclaration: str

“1” if checkbox checked next to “I certify that I do not have a criminal record”

notPoliticallyExposedPeron: str

“1” if checkbox checked next to “I certify that I am not a politically exposed person or government official”

notCrimeaOrSevastopool: str (optional)

Only show this field if the user selected UKR (ukraine) for “country”
“1” if checkbox checked next to “I certify that I am not a resident of Crimea or Sevastopol”

chatApp: str (optional)

Below “You are welcome (but not obligated) to fill in the fields below. They help us provide account support.”
Options are “telegram”, “wechat”, “kakaotalk”, or other

chatHandle: str (optional)

Also below the “You are welcome…” text
This is their chat username

Submitting Level 2 KYC

POST https://ftx.com/api/kyc/

Notes:

Some required fields here have type “file”. That means that in the form submitted, they’re an <input type=”file”...> that allows multipart submission and accepts *.
Display somewhere by the requests for ID: “Acceptable forms of valid identification include passport, driver’s license, identity card or any other government-issued ID.”

Form Data:

country: str
fullLegalName: str
fullLegalNameEnglish: str

If from Korea, Ukraine, or Russia, or using non-latin characters
Display “Must match name on government-issued ID”

documentIssuer: str

Display “ID Document Country”

address: str

Show this if “country” is not CHN or SGP (since those countries have address on ID)
Display “Residential or business street address”

proofOfAddress: file

Display: “Proof of Address”, “Such as a recent utility bill, bank statement, lease agreement, or government ID with address”

idDocFront: file

Display: “ID Document Front”

idDocBack: file

Display: “ID Document Back”

idDocSelfie: file

Display: “Please provide a photo of you holding your ID and a piece of paper containing today's date and the text ‘FTX’”

sourceOfFunds: str

“Income”, “trading”, or “other”

sourceOfFundsDetails: str (only show if they supplied “other” in the sourceOfFunds field)

Display: “Description of source of the individuals’s assets”

stateProvinceRegion: str

The state, region, or province they reside in

noCriminalRecordDeclaration: str

“1” if checkbox checked next to “I certify that I do not have a criminal record”

notPoliticallyExposedPerson: str

“1” if checkbox checked next to “I certify that I am not a politically exposed person or government official”

notCrimeaOrSevastopool: str (optional)

Only show this field if the user selected UKR (ukraine) for “country”
“1” if checkbox checked next to “I certify that I am not a resident of Crimea or Sevastopol”

chatApp: str (optional)

Below “You are welcome (but not obligated) to fill in the fields below. They help us provide account support.”
Options are “telegram”, “wechat”, “kakaotalk”, or other

chatHandle: str (optional)

Also below the “You are welcome…” text
This is their chat username

Important note about proofOfAddress

You can skip supplying proofOfAddress and instead supply proof of phone number ownership:

To request an SMS, send a JSON POST request to /api/mfa/sms/setup, passing in the phone number as phoneNumber
Include the phone number and SMS code in the request to /api/kyc/ as phoneNumber and smsCode, respectively

Phone numbers should include the country code (e.g. +14155551234)

For level 2 KYC on international, we accept phone number if the country of residency, document issuing country, and phone number country all match; otherwise the user should provide a proof of address.

Important note about idDocFront, idDocBack, idDocSelfie

Periodically send GET requests to /api/kyc/jumio?lang=en. The lang parameter should be one of the options in https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#supported-locale-values

This returns one of the following:

{'status': 'pending', 'url': 'https://ftx.netverify.com/...'}: App should display the provided URL in a webview, with a toggle to opt out in case Jumio isn't working
{'status': 'success', 'documentIssuer': 'USA'}: Jumio was successful, can skip the document/selfie upload and continue to SMS
{'status': 'error'}: Jumio failed, and so you should show document/selfie upload (idDocFront, idDocBack, idDocSelfie) instead