browse

Whitelabeling FTX US

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

This article gives an overview of how to add FTX US 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.us/

For the 2FA section, please try to emulate what the FTX US 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.us/

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.us/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.us/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.us/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
    • Explained further in the KYC section below
    • Explained further in the KYC section below
    • kycLevel: int
    • kycApplicationStatus: str
    • displayName: str
    • email: str
    • referrerId: int
    • vip: bool
    • feeTier: int
  • mfaRequired: bool

Login with MFA

POST https://ftx.us/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.us/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.us/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.us/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.us/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.us/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.us/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.us/hc/en-us/articles/360048666713-Account-Tiers-and-Limits
    • 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 US altogether
    • This means that users start out with kycApplicationStatus ‘not_started’

Submitting Level 1 KYC

POST https://ftx.us/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.us/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 US’”
  • 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

Updating login passwords

Request password reset code

POST https://ftx.us/api/users/whitelabel/change_password

Params:

  • email: string

Returns:

  • code: string

Complete password reset

POST https://ftx.us/api/users/whitelabel/complete_password_reset

Params:

  • email: string
  • code: string
  • password: string

Returns:

  • Nothing of note -- a ‘Success’ string if successful
 

Comments

0 comments

Article is closed for comments.

Was this article helpful?

0 out of 0 found this helpful
Powered by Zendesk