OAuth

Third party services can access Liquid resources and information, on behalf of Liquid users.

OAuth Application

To use OAuth services, an OAuthApplication must be created. Contact Liquid partner services to apply.

OAuth Request

Create an empty OAuth request.

Request

POST /system/oauth_requests

X-Quoine-Auth: {(OAuth Approved, External App) User Token}
{
  external_ref: "external reference, not used by liquid"
}

Response

200
{
  oauth_request_public_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  oauth_request_private_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  expires: "{oauth_request.expires}",
  app_challenge_href:
  "https://app.liquid.com/oauth?ref=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    api_challenge_href:
  "https://api.liquid.com/oauth/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/approve"
}

User Approval

The response to the OAuthRequest returns app_challenge_href which is a URL that will prompt the user to approve the request.

Create and Sign OAuth JWT

After an OAuthRequest is approved by the user, the associated oauth_request_public_id and oauth_request_private_id can then be used in a JWT to access services on behalf of that user.

function createJwt(path, liquid_token_id, liquid_token_secret, oauth_request_public_id, oauth_request_private_id) {
    return jwt.encode(
        {
            token_id: liquid_token_id,
            path: path,
            nonce: Date.now(),
            oauth_request_public_id: oauth_request_public_id,
            oauth_request_private_id: oauth_request_private_id
        }, 
        liquid_token_secret
    );
}

Fetch User Information

Request

GET https://api.liquid.com/user/context
X-Quoine-Auth: createJwt('/user/context', ...)

Response

200
{
  "user_id": number;
  "token_id": string;
  "trading_account_ids": Array<number>,
  "app_vendor_id": number;
  "country": string;
  "status": LIQUID_USER_KYC_STATUS;
  "currency": string;
  "language": string;
  "user_type": string;
  "has_proof_address":true,
  "has_id_document":true,
  "avatar":null,
  "affiliate_code": string;
  "is_fully_verified":true,
  "email_confirmed_at": number;
  "declined_reason":null,
  "modules":{[module: string]: Array<string>},
  "first_name": string;
  "last_name": string;
  "email": string;
  "permissions": Array<string>;
}

Fetch User Accounts

Request

GET https://api.liquid.com/accounts
X-Quoine-Auth: createJwt('/accounts', ...)

Response

200
{
    "crypto_accounts": [
        {
            "id": 1111,
            "currency": "BTC",
            "balance": "0.06",
            "reserved_balance": "0.0",
            "pusher_channel": "user_1111_account_btc",
            "lowest_offer_interest_rate": "0.00002",
            "highest_offer_interest_rate": "0.00200",
            "address": "1FePLaYMejoo37CjLyzovJGMVTPPGQ3SVM",
            "currency_symbol": "₿",
            "minimum_withdraw": "0.02",
            "currency_type": "crypto"
        }
    ],
    "fiat_accounts": [
        {
            "id": 979984,
            "currency": "USD",
            "balance": "0.00726",
            "reserved_balance": "0.0",
            "pusher_channel": "user_1111_account_usd",
            "lowest_offer_interest_rate": null,
            "highest_offer_interest_rate": null,
            "currency_symbol": "$",
            "send_to_btc_address": null,
            "exchange_rate": "1.0",
            "currency_type": "fiat"
        }
    ]
}