POST /v1/oauth2/token

Returns access token as well as refresh token.

When the access token is expired, your app can obtain a new token as described in Reissue Access Token section below.

This method requires HTTP header Content-type: application/x-www-form-urlencoded.

Access Token Initial Obtaining

POST /v1/oauth2/token
Content-type: application/x-www-form-urlencoded

{
  "grant_type": "password",
  "scope": "general",
  "username": "(string)",
  "password" "(string)",
  "client_id": "waves.exchange"
}

Request parameters

Field name	Description
grant_type	To initially obtain an access token specify password
scope	Specify general
username	User's public key (opens new window)
password	Generate password as follows: 1. Join chain ID (opens new window) character with client_id string and with token expiration Unix timestamp in seconds, using ':' separator. For example, W:waves.exchange:1584651600. 2. Convert this string to bytes. 3. Add [255, 255, 255, 1] prefix. 4. Generate Curve25519 (opens new window) signature of bytes using user's private key (opens new window). 5. Join token expiration Unix timestamp in seconds with base58 encoded signature, using ':' separator. For example, 1584651600:3BU36da1h6Bzhs4tKcfkCsXWi4vEgP8eQD7rkGWJdxbRfNpky6p3p7mUJWEL9ejDsasS8nWu1g6tZpsX4. ⚠️Token expiration timestamp must be no more than a week from the current time. See also the JavaScript Example section below.
client_id	For Gateway API specify waves.exchange

Response JSON Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw...",
  "token_type": "bearer",
  "expires_in": 1584651600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw..."
}

Response Parameters

Field name	Description
access_token	Access token to use in API requests
token_type	Type of token issued. Always takes the value bearer
expires_in	Access token expiration timestamp: Unix time in seconds
refresh_token	Refresh token. After access token expiration you can exchange refresh token for a new access token, see the Reissue Access Token section below

JavaScript Example

The example uses waves-transactions library, see documentation (opens new window) on Github.

import { libs } from "@waves/waves-transactions";

const seed = "insert your seed here";
const chain_code = "W"; // "T" for Testnet
const client_id = "waves.exchange";
const seconds = Math.round((Date.now() + 1000 * 60 * 60 * 24 * 7) / 1000); // Token for a week

const bytes = [255, 255, 255, 1, ...libs.crypto.stringToBytes(`${chain_code}:${client_id}:${seconds}`)];
const signature = libs.crypto.signBytes(seed, bytes);            

fetch('https://api.waves.exchange/v1/oauth2/token', {
    method: 'POST',
    headers: {
        'Content-type': 'application/x-www-form-urlencoded'
    },
    body: [
        "grant_type=password",
        "scope=general",
        `username=${encodeURIComponent(libs.crypto.publicKey(seed))}`,
        "password=" + encodeURIComponent(`${seconds}:${signature}`),
        `client_id=${client_id}`
    ].join('&')
});

Example of Getting Token via Signer

import { Signer } from '@waves/signer';
import { ProviderWeb } from '@waves.exchange/provider-web';

async function getToken() {
    const provider = new ProviderWeb(url, true);
    const signer = new Signer({ NODE_URL: node });
    signer.setProvider(provider);

    const client_id = "waves.exchange";
    const chain_code = "W";
    const seconds = Math.round((Date.now() + 1000 * 60 * 60 * 24 * 7) / 1000);
    const message = `${chain_code}:${client_id}:${seconds}`;

    const { publicKey } = await signer.login();
    const signature = await signer.signMessage(message);
    const url = `https://api.waves.exchange/v1/oauth2/token`;
    const data = await fetch(url, {
        method: 'POST',
        headers: {
            'Content-type': 'application/x-www-form-urlencoded'
        },
        body: [
            "grant_type=password",
            "scope=general",
            `username=${encodeURIComponent(publicKey)}`,
            "password=" + encodeURIComponent(`${seconds}:${signature}`),
            `client_id=${client_id}`
        ].join('&')
    }).then(result => result.json());

   return data.access_token;
}


const token = await getToken();

Example of Getting Token via Metamask Provider

import { Signer } from '@waves/signer';
import { ProviderMetamask } from '@waves/provider-metamask';
import { wavesAddress2eth } from '@waves/node-api-js';


async function getToken() {
    const chain_code = "W";
    const node = "https://nodes.wavesnodes.com";
    const provider = new ProviderMetamask({
        wavesConfig: {
            nodeUrl: node,
            chainId: chain_code.charCodeAt(0)
        }
    });

    const signer = new Signer({ NODE_URL: node });
    signer.setProvider(provider);

    const client_id = "waves.exchange";
    const seconds = Math.round((Date.now() + 1000 * 60 * 60 * 24 * 7) / 1000);
    const message = `${chain_code}:${client_id}:${seconds}`;

    const user = await signer.login();
    const ethereumAddress = wavesAddress2eth(user.address);

    const signature = await signer.signMessage(message);
    const url = `https://api.waves.exchange/v1/oauth2/token`;
    const data = await fetch(url, {
        method: 'POST',
        headers: {
            'Content-type': 'application/x-www-form-urlencoded'
        },
        body: [
            "grant_type=password",
            "scope=general",
            `username=${encodeURIComponent(ethereumAddress)}`,
            "password=" + encodeURIComponent(`${seconds}:${signature}`),
            `client_id=${client_id}`
        ].join('&')
    }).then(result => result.json());

   return data.access_token;
}


const token = await getToken();

Reissue Access Token

POST /v1/oauth2/token
Content-type: application/x-www-form-urlencoded

{
  "grant_type": "refresh_token",
  "scope": "general",
  "client_id": "waves.exchange",
  "refresh_token": "(string)"
}

Request parameters

Field name	Description
grant_type	To exchange a refresh token for a new access token specify refresh_token
scope	Specify general
client_id	For Gateway API specify waves.exchange
refresh_token	Refresh token. After access token expiration you can exchange refresh token for a new access token

Response JSON Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw...",
  "token_type": "bearer",
  "expires_in": 1584109637,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw..."
}

Response parameters are the same as described in the Access Token Initial Obtaining section.

JavaScript Example

const refresh_token = "insert your refresh token here";
const client_id = "waves.exchange";

fetch('https://api.waves.exchange/v1/oauth2/token', {
    method: 'POST',
    headers: {
        'Content-type': 'application/x-www-form-urlencoded'
    },
    body: [
        "grant_type=refresh_token",
        "scope=general",
        `refresh_token=${refresh_token}`,
        `client_id=${client_id}`
    ].join('&')
});