Create a User

Required user data

To create a new user we require the following user data:

  • First name

  • Last name

  • Email

  • Country

  • Mobile Phone number

  • We also require that each user agree to our terms of use. The user must explicitly select a checkbox with the following label and link: “I agree to the Ratio terms of use.”

While we do not recommend capturing additional data before creating a user, there are additional user data fields required to submit a request for KYC approval. In most cases, KYC will be the next step in your user journey after creating the user, and in most cases, you will want to collect this information after the user account is created. The required fields for submitting a request for KYC approval are:

  • Date of Birth

  • ID type: *SSN

  • ID Number

  • Address Line 1

  • Address Line 2

  • City

  • State

  • Postal Code

Create a user session

User authentication is required to create a session. A JWT will be provided after the user authenticates, and must be included in the header of all API calls.

Any one of the three authentication factors below can be used to obtain a session token:

  • Wallet (aka. Sign in With Ethereum / Connect Wallet)

  • SMS One-time Passcode*

  • Email One-time Passcode

*SMS OTP must be included as one of the two authentication factors when creating a user

First authentication factor

For the best user experience use Wallet as the first user authentication factor

Wallet authentication includes two steps:

  1. Retrieve a challenge to be signed by the user's wallet

{
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletType": "EVM"
}
curl --location -g --request POST 'https://api.ratio.me/v1/auth/cryptoWallet:start' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "walletAddress": "<WALLET_ADDRESS>",
    "walletType": "EVM"
}'
  1. Then pass back the signature alongside the wallet address

{
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletType": "EVM",
    "signature": "2djd2cFZ9VU2zDWvUGqeHwvbiJZfTt3BMzDctDsEW7vM2QUTgTHjeM2rpFX9ZULeic3KptUh5ehipXDFcK5ecYiX"
}
curl --location -g --request POST 'https://api.ratio.me/v1/auth/cryptoWallet:authenticate' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "walletAddress": "<WALLET_ADDRESS>",
    "walletType": "EVM",
    "signature": "<SIGNED_CHALLENGE_STRING>"
}'

After authenticating the user, you will receive a JWT that must be provided in the Authorization header for all subsequent requests within that user session.

Second authentication factor

Reminder: SMS must be one of your authentication factors to create a user

First, we need to send a one-time code to the user using the phone number they provided during sign-up.

{
    "phoneNumber": "+14165551234",
}
curl --location --request POST 'https://api.ratio.me/v1/auth/otp/sms:send' \
--header 'Authorization: Bearer eyJ......' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phoneNumber": "+14165551234"
}'

Once you receive the one-time code send it (with the phone id received in the first response) to the sms:authenticate endpoint to obtain a JWT.

{
    "phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
    "otp": "123456",
}
curl --location --request POST 'https://api.ratio.me/v1/auth/otp/sms:authenticate' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Authorization: Bearer eyJ......' \
--header 'Content-Type: application/json' \
--data-raw '{
    "otp": "123456",
    "phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789"
}'

Create the user

At this point, you can create a user

Next steps

After creating a user there are three additional requirements before you can initiate payments:

You are free to complete the remaining tasks in any order, however, we recommend the sequence above.

Our recommended next step is to assign a deposit address

Last updated

Was this helpful?