The Upvest Blockchain API

A multi-protocol blockchain API for building blockchain-interacting applications.

Get Started     Tutorial     API Reference

API Key Authentication

Before being able to sign any requests as a tenant, you must create an API key via the Account Management. Upon creating a key, there are three pieces of information which you must remember:

  • key,
  • secret, and
  • passphrase.

The key and secret are randomly generated and provided by Upvest. the passphrase is provided by you to further secure your API access. Upvest stores a salted hash (using an impermanent and long salt) of your passphrase for verification, and, thus, cannot recover the passphrase if you forget it.

📘

Important

You must sign all requests to prevent altering the payload in flight.

Creating a Request

All HTTP requests as a tenant must contain the following message headers:

  • X-UP-API-Key The API key as a string.
  • X-UP-API-Passphrase The passphrase you specified when creating the API key.
  • X-UP-API-Timestamp A timestamp for your request (see Timestamps).
  • X-UP-API-Signature The hex-encoded signature (see Signing a Request).
  • X-UP-API-Signed-Path The path used in the signature (see Signing a Request).

All message payloads must be formatted using JSON, and the Content-Type header field must be set to the application/json media type.

Signing a Request

You generate the X-UP-API-Signature value by creating a hash-based message authentication code (HMAC) using the SHA-512 cryptographic hash function and your secret cryptographic key from your API key on the pre-hashed message. The pre-hashed message is a concatenated string of timestamp, method, path, and body. Finally, hex-encode the HMAC digest output.

timestamp

📘

Example

1543315873.80233

The timestamp is the number of seconds since the Unix Epoch in UTC. Fractions of a second are allowed. The timestamp must be the same string representation as used in the X-UP-API-Timestamp message header.

See also the Timestamps section for more information.

method

📘

Example

POST

The method is the HTTP request method and is uppercased.

path

📘

Example

/1.0/tenancy/users/?cursor=abc

The path is the path component of the request URL, including query parameters and leading and trailing slashes (if any).

body

📘

Example

{ "echo": "Hello, world!" }

body is the exact string used as the HTTP message body.

Use an empty string if there is no HTTP message body, which is typical for HTTP GET requests.

📘

Important

To obtain the exact body string, you might have to serialize the request message payload to JSON and hand it to your HTTP request library to use as the request body. Do not rely on your library to JSON serialize the message payload for you, which might result in a different JSON string representation as the request body and therefore as a different signature against which the API server checks.

📘

Important

Remember to hex-encode the HMAC digest output before sending it in the X-UP-API-Signature message header.

Examples

const crypto = require("crypto");

// Before implementation, set the `API_KEY`, `API_SECRET`,
// and `API_PASSPHRASE` (preferably as environment variables).
const API_KEY = "API_KEY";
const API_SECRET = "API_SECRET";
const API_PASSPHRASE = "API_PASSPHRASE";

const timestamp = `${Math.floor(Date.now() / 1000)}`;
const method = "POST";
const path = "/1.0/tenancy/users/";
const payloadBody = { username: "jane", password: "very secret" };
const body = JSON.stringify(payloadBody);
const message = `${timestamp}${method}${path}${body}`;
const hmac = crypto.createHmac("sha512", API_SECRET).update(message)
const signature = hmac.digest("hex");
const headers = {
    "Content-Type": "application/json",
    "X-UP-API-Key": API_KEY,
    "X-UP-API-Passphrase": API_PASSPHRASE,
    "X-UP-API-Timestamp": timestamp,
    "X-UP-API-Signature": signature,
    "X-UP-API-Signed-Path": path
};

// Make your HTTP request using the message headers defined above.
import time
import json
import hmac
import hashlib
import requests

# Before implementation, set the `API_KEY`, `API_SECRET`,
# and `API_PASSPHRASE` (preferably as environment variables).
API_KEY = 'API_KEY'
API_SECRET = 'API_SECRET'
API_PASSPHRASE = 'API_PASSPHRASE'

timestamp = str(int(time.time()))
method = 'POST'
path = '/1.0/tenancy/users/'
payload_body = { "username": "jane", "password": "very secret" }
body = json.dumps(payload_body)
message = timestamp+method+path+body
signature = hmac.new(
    str.encode(API_SECRET),
    message.encode('utf-8'),
    digestmod=hashlib.sha512).hexdigest()
headers = {
    'Content-Type': 'application/json',
    'X-UP-API-Key': API_KEY,
    'X-UP-API-Passphrase': API_PASSPHRASE,
    'X-UP-API-Timestamp': timestamp,
    'X-UP-API-Signature': signature,
    'X-UP-API-Signed-Path': path
}

# Make your HTTP request using the message headers defined above.

Timestamps

The X-UP-API-Timestamp message header is the number of seconds since the Unix Epoch in UTC. Fractions of a second are allowed.

Your timestamp must be within 30 seconds of the API service time, or your request is considered expired and is rejected. We recommend using the time endpoint to query for the API server time if you believe there may be time skew between your server and the API servers. After using a timestamp, it is not permitted to use it again (effectively functioning as a nonce), and the timestamp must always increase for each request. Note, you can increase the fractional part if you are sending another request within the same second.

Updated 7 months ago


API Key Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.