Authentication

Prerequisites

You create API keys in Payward Console. Sandbox and production each have their own Console, listed in Environments, and a key works only in the environment where you created it. To get access to the sandbox Console, see Get sandbox access.
Some examples on this page act on an account. To find your account ID, see Find your account ID.

Authentication parameters

The Payward Services API uses HMAC signing. Every authenticated request must include the following headers:

API-Key HTTP header parameter: your public API key.
API-Timestamp HTTP header parameter: the time you signed the request, as Unix time in milliseconds.
API-Sign HTTP header parameter: HMAC-SHA512 signature of the request.

Which version does my key use?

API keys use one of two signing versions: V2 (timestamp), described on this page, and V1 (nonce), the legacy version. Use V2 for every new integration. With V1, each nonce must be larger than the last one the API received for that key, so servers that share a key must coordinate their nonces. With V2, the API accepts any recent timestamp, in any order.

To see a key’s version, open it in API keys in Payward Console. If its details show a Signature version, that’s the version it uses. Otherwise, ask your Payward contact.
If your key uses V1, keep signing its requests as described in V1 signing (legacy).
To move to V2, ask your Payward contact to migrate your existing keys. They’ll tell you when to switch your integration to V2 signing. You can also create a new key that uses V2.

Setting the `API-Key` parameter

The value for the API-Key HTTP header parameter is your public API key. In Payward Console, open API keys and select Create key. Give the key a name, choose its purpose, set an expiration date if needed, and select only the scopes your integration needs. The examples on this page need two scopes: query-funds for the portfolio requests and modify-trades for creating a quote. Listing webhooks needs no scope. If the form offers a choice of signature version, choose V2 (timestamp).

Payward Console form for creating an API key

Payward Console shows your API secret only once, when you create the key. Copy it then, and store it securely.

Your API key, which you can copy from the Key column in API keys, is sent in the API-Key header parameter.
Your API secret is never sent. It’s only used to compute the signature for the API-Sign header parameter. It’s a base64 string, like the one in the test vectors.

Payward Console confirms that the API secret must be stored before it is hidden

Setting the `API-Timestamp` parameter

Set API-Timestamp to the current Unix time in milliseconds, as a decimal string, such as 1700000000000. Read it from the system clock, such as time.time_ns() // 1_000_000 in Python or Date.now() in JavaScript. Timers with an arbitrary origin, such as process.hrtime() in Node.js, don’t return Unix time. Take a new timestamp for every request, including every retry. See Retries and duplicate requests. The API accepts a timestamp up to 15 seconds before or after its own time, and rejects the request otherwise. Keep your servers’ clocks synchronized with NTP (Network Time Protocol).

Setting the `API-Sign` parameter

The value for the API-Sign HTTP header parameter is a base64-encoded HMAC-SHA512 signature of a four-line signing string:

body_hash      = UPPERCASE_HEX(SHA256(body))
signing_string = timestamp + "\n" + UPPERCASE(method) + "\n" + path_with_query + "\n" + body_hash
API-Sign       = base64(HMAC-SHA512(base64decode(api_secret), utf8(signing_string)))

Algorithm steps

Take the timestamp: use the exact value you send in API-Timestamp.
Take the method: use the HTTP method in uppercase, such as GET or POST.
Take the request target: use the path and query string exactly as you send them, such as /v1/webhooks or /v1/accounts/{account_id}/portfolio?quote_symbol=EUR. Leave out the scheme, host, port, and fragment. Keep the percent-encoding exactly as sent.
Hash the body: compute the SHA-256 digest of the exact body bytes you send, and write it in uppercase hexadecimal. For any request without a body, hash empty bytes, which gives E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855.
Build the signing string: join the timestamp, method, request target, and body hash with newline characters (\n), in that order. Don’t add a trailing newline.
Sign: compute HMAC-SHA512 over the UTF-8 bytes of the signing string. Use your API secret, base64-decoded, as the HMAC key.
Encode: base64-encode the signature. The result is the API-Sign value.

Examples

The following helpers sign requests in Python and JavaScript. They read your credentials from PWS_API_KEY and PWS_API_SECRET, and the API base URL from PWS_BASE_URL. Set PWS_BASE_URL to the sandbox or production base URL, listed in Environments.

payward_signature (paywardSignature in JavaScript) computes the API-Sign value from its arguments. It reads no clock and no environment variable, so you can unit-test it with the test vectors.
signed_headers (signedHeaders) takes the current time, signs the request, and returns every header to send: API-Key, API-Timestamp, and API-Sign. It adds Content-Type: application/json when the request has a body. With idempotent=True ({ idempotent: true }), it also adds a new Idempotency-Key. Each call creates a new key, so to retry an operation safely, create the key yourself and reuse it, as shown in Retries and duplicate requests.

Pass the body as the exact string you send, and the path as the exact request target you send. The guides on this site use the same helpers.

import base64
import hashlib
import hmac
import json
import os
import time
import uuid
from urllib.parse import urlencode

import requests

API_KEY = os.environ["PWS_API_KEY"]
API_SECRET = os.environ["PWS_API_SECRET"]
BASE_URL = os.environ["PWS_BASE_URL"]


def payward_signature(secret, timestamp, method, path_with_query, body=""):
    """Return the API-Sign value for one request.

    body is the exact string sent on the wire, or "" for a request without a body.
    """
    body_hash = hashlib.sha256(body.encode("utf-8")).hexdigest().upper()
    message = f"{timestamp}\n{method.upper()}\n{path_with_query}\n{body_hash}"
    mac = hmac.new(base64.b64decode(secret), message.encode("utf-8"), hashlib.sha512)
    return base64.b64encode(mac.digest()).decode()


def signed_headers(method, path_with_query, body="", idempotent=False):
    """Return the headers for one request, signed now."""
    timestamp = str(time.time_ns() // 1_000_000)
    headers = {
        "API-Key": API_KEY,
        "API-Timestamp": timestamp,
        "API-Sign": payward_signature(
            API_SECRET, timestamp, method, path_with_query, body
        ),
    }
    if body:
        headers["Content-Type"] = "application/json"
    if idempotent:
        headers["Idempotency-Key"] = str(uuid.uuid4())
    return headers

import crypto from 'node:crypto';

const API_KEY = process.env.PWS_API_KEY;
const API_SECRET = process.env.PWS_API_SECRET;
const BASE_URL = process.env.PWS_BASE_URL;

/**
 * Returns the API-Sign value for one request.
 * `body` is the exact string sent on the wire, or '' for a request without a body.
 */
function paywardSignature(secret, timestamp, method, pathWithQuery, body = '') {
  const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('hex').toUpperCase();
  const message = `${timestamp}\n${method.toUpperCase()}\n${pathWithQuery}\n${bodyHash}`;
  return crypto.createHmac('sha512', Buffer.from(secret, 'base64')).update(message, 'utf8').digest('base64');
}

/** Returns the headers for one request, signed now. */
function signedHeaders(method, pathWithQuery, body = '', { idempotent = false } = {}) {
  const timestamp = String(Date.now());
  const headers = {
    'API-Key': API_KEY,
    'API-Timestamp': timestamp,
    'API-Sign': paywardSignature(API_SECRET, timestamp, method, pathWithQuery, body),
  };
  if (body) {
    headers['Content-Type'] = 'application/json';
  }
  if (idempotent) {
    headers['Idempotency-Key'] = crypto.randomUUID();
  }
  return headers;
}

Test vectors

To check your own signer, reproduce the signatures of these two requests. They use fake key material:

API key:       test-api-key
API secret:    AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==
API-Timestamp: 1700000000000

`GET` with a query string and no body

Request:

GET /v1/reports/settlement?start_date=2026-04-25T00%3A00%3A00Z&end_date=2026-04-26T00%3A00%3A00Z&report_type=swaps

Signing string:

1700000000000
GET
/v1/reports/settlement?start_date=2026-04-25T00%3A00%3A00Z&end_date=2026-04-26T00%3A00%3A00Z&report_type=swaps
E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855

Headers:

API-Key: test-api-key
API-Timestamp: 1700000000000
API-Sign: G7vQQwhG76ulpVc7TtF5kqUhNq54RgS6vRAmeKgo8GFTmhThUwNTcOR+ERS9f8be3MCMMpBRZx5czkr80KLnxQ==

`POST` with a body and no query string

Request, with the body on the second line:

POST /v1/users
{"email":"[email protected]","external_reference":"partner-user-12345"}

Signing string:

1700000000000
POST
/v1/users
ECA9CFFED74812D0296C6DCFAA68C00E9E2FF07D6C860B6ADD6F73A572584E20

Headers:

API-Key: test-api-key
API-Timestamp: 1700000000000
API-Sign: IKV68BHeOPFZEUajDgwOQox194xE9rU0Nh5IjDSt8d12qcm4IhcVmbTNzxLZxCOraIWxxrhOzX17HDOudviyeA==

The same checks as unit tests for the helpers above:

SECRET = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw=="
TIMESTAMP = "1700000000000"

assert (
    payward_signature(
        SECRET,
        TIMESTAMP,
        "GET",
        "/v1/reports/settlement?start_date=2026-04-25T00%3A00%3A00Z&end_date=2026-04-26T00%3A00%3A00Z&report_type=swaps",
    )
    == "G7vQQwhG76ulpVc7TtF5kqUhNq54RgS6vRAmeKgo8GFTmhThUwNTcOR+ERS9f8be3MCMMpBRZx5czkr80KLnxQ=="
)

assert (
    payward_signature(
        SECRET,
        TIMESTAMP,
        "POST",
        "/v1/users",
        '{"email":"[email protected]","external_reference":"partner-user-12345"}',
    )
    == "IKV68BHeOPFZEUajDgwOQox194xE9rU0Nh5IjDSt8d12qcm4IhcVmbTNzxLZxCOraIWxxrhOzX17HDOudviyeA=="
)

import assert from 'node:assert/strict';

const SECRET = 'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==';
const TIMESTAMP = '1700000000000';

assert.equal(
  paywardSignature(
    SECRET,
    TIMESTAMP,
    'GET',
    '/v1/reports/settlement?start_date=2026-04-25T00%3A00%3A00Z&end_date=2026-04-26T00%3A00%3A00Z&report_type=swaps',
  ),
  'G7vQQwhG76ulpVc7TtF5kqUhNq54RgS6vRAmeKgo8GFTmhThUwNTcOR+ERS9f8be3MCMMpBRZx5czkr80KLnxQ==',
);

assert.equal(
  paywardSignature(
    SECRET,
    TIMESTAMP,
    'POST',
    '/v1/users',
    '{"email":"[email protected]","external_reference":"partner-user-12345"}',
  ),
  'IKV68BHeOPFZEUajDgwOQox194xE9rU0Nh5IjDSt8d12qcm4IhcVmbTNzxLZxCOraIWxxrhOzX17HDOudviyeA==',
);

Complete request example

Here’s a complete example making an authenticated GET request to list your webhooks. Add it after the helpers, in the same file. Run the JavaScript version as an ES module, for example saved as list-webhooks.mjs.

def list_webhooks():
    path = "/v1/webhooks"
    response = requests.get(
        BASE_URL + path, headers=signed_headers("GET", path), timeout=10
    )
    response.raise_for_status()
    return response.json()


webhooks = list_webhooks()
print(webhooks)

async function listWebhooks() {
  const path = '/v1/webhooks';
  const response = await fetch(BASE_URL + path, { method: 'GET', headers: signedHeaders('GET', path) });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}

const webhooks = await listWebhooks();
console.log(webhooks);

If you haven’t registered any webhooks yet, the response is an empty list:

{ "data": [] }

An empty list still means your request was authenticated. If the key or signature is wrong, you get 401 Unauthorized instead, which the example raises as an error. See Troubleshooting.

Query parameters in signature

When your request includes query parameters, sign the path together with its query string. Build that string once, and use it both to sign and to send the request, so the encoding you sign is the encoding you send. Build the query string with urlencode() in Python or URLSearchParams in JavaScript, and send that exact string. In Python, don’t encode characters such as ~ as %7E by hand: requests decodes them before sending, so the request no longer matches its signature. The examples in this section and the next one call account-scoped endpoints. They read the account ID from PWS_ACCOUNT_ID. To find it, see Find your account ID. A user ID won’t work in its place. See Users, accounts, and ownership.

account_id = os.environ["PWS_ACCOUNT_ID"]
# Pass booleans as lowercase strings: urlencode() would turn True into "True".
query = urlencode({"quote_symbol": "EUR", "with_zero_balances": "true"})
path = f"/v1/accounts/{account_id}/portfolio?{query}"

response = requests.get(
    BASE_URL + path, headers=signed_headers("GET", path), timeout=10
)
response.raise_for_status()

const accountId = process.env.PWS_ACCOUNT_ID;
const query = new URLSearchParams({ quote_symbol: 'EUR', with_zero_balances: 'true' });
const path = `/v1/accounts/${accountId}/portfolio?${query}`;

const response = await fetch(BASE_URL + path, { method: 'GET', headers: signedHeaders('GET', path) });
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

Don’t pass the parameters to your HTTP client separately, such as with params= in requests. The client then encodes the query string itself, and the result can differ from the string you signed.

Request body in signature

For requests that send a body (POST, PUT, PATCH), the body bytes used to compute the signature must match the bytes sent on the wire exactly. Differences in whitespace, key ordering, or encoding produce a signature mismatch. Serialize the body once, and pass the same string to signed_headers and to the HTTP request:

account_id = os.environ["PWS_ACCOUNT_ID"]
path = f"/v1/accounts/{account_id}/quotes"
body = json.dumps(
    {
        "from": {"symbol": "USD", "type": "fiat", "amount": "100.00"},
        "to": {"symbol": "BTC", "type": "crypto"},
    }
)

# Send the same string with data=. Passing json= would serialize the body again.
response = requests.post(
    BASE_URL + path,
    headers=signed_headers("POST", path, body),
    data=body,
    timeout=10,
)
response.raise_for_status()

const accountId = process.env.PWS_ACCOUNT_ID;
const path = `/v1/accounts/${accountId}/quotes`;
const body = JSON.stringify({
  from: { symbol: 'USD', type: 'fiat', amount: '100.00' },
  to: { symbol: 'BTC', type: 'crypto' },
});

const response = await fetch(BASE_URL + path, {
  method: 'POST',
  headers: signedHeaders('POST', path, body),
  body,
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

For a request without a body, don’t pass one. The helpers then sign an empty body and leave out Content-Type.

Retries and duplicate requests

The API rejects a request that exactly repeats an earlier one, with the same timestamp, method, request target, and body. Because the timestamp is signed, a copy can’t be given a new one, so once the timestamp is too old, the API rejects the copy anyway. To make sure the API doesn’t reject your own requests:

Don’t send two identical requests in the same millisecond. They get the same timestamp and signature, so the API rejects the second one.
Sign every retry again, with a new timestamp. Don’t resend the headers of an earlier attempt.
If the endpoint takes an Idempotency-Key header, listed among its parameters in the API reference, send the same key with every retry of an operation. The new signature makes each attempt a new request, and the shared key tells the API that they’re the same operation.

This example retries a request when no response arrives, such as after a timeout or a dropped connection:

def post_with_retries(path, body, attempts=3):
    # One key for the operation, reused by every attempt.
    idempotency_key = str(uuid.uuid4())
    for attempt in range(attempts):
        # Sign every attempt again, so that each one gets a new timestamp.
        headers = {
            **signed_headers("POST", path, body),
            "Idempotency-Key": idempotency_key,
        }
        try:
            return requests.post(
                BASE_URL + path, headers=headers, data=body, timeout=10
            )
        except (requests.ConnectionError, requests.Timeout):
            if attempt == attempts - 1:
                raise
            time.sleep(2**attempt)

async function postWithRetries(path, body, attempts = 3) {
  // One key for the operation, reused by every attempt.
  const idempotencyKey = crypto.randomUUID();
  for (let attempt = 0; ; attempt++) {
    // Sign every attempt again, so that each one gets a new timestamp.
    const headers = { ...signedHeaders('POST', path, body), 'Idempotency-Key': idempotencyKey };
    try {
      return await fetch(BASE_URL + path, { method: 'POST', headers, body, signal: AbortSignal.timeout(10_000) });
    } catch (error) {
      if (attempt === attempts - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * 2 ** attempt));
    }
  }
}

Troubleshooting

Authentication failures return 401 Unauthorized with "code": "gateway" in the error body, whatever the cause, so the response doesn’t say which check failed. The exception is a request that sends both API-Timestamp and API-Nonce, which returns 400 Bad Request with the same code. Find the cause from what you see:

Symptom	Cause	Fix
Your signer doesn’t reproduce the test vectors.	Signer bug: the signing string or the HMAC key is wrong.	Compare your signing string with the test vectors, line by line. Use your API secret, base64-decoded, as the HMAC key.
Every request fails, though your signer reproduces the test vectors.	Wrong credentials or headers: the API secret doesn’t belong to the API key, the key was created in another environment, or a header is missing or misspelled.	Use an API key and its API secret, created in the environment you call. Send all three headers: `API-Key`, `API-Timestamp`, and `API-Sign`.
Requests with a key that used to work now all fail.	Expired or revoked key: the API rejects the key as unknown.	Check the key’s expiration date in API keys in Payward Console, including under Show revoked keys. If it has expired or been revoked, create a new key.
Every request fails, and the key uses V1 (nonce).	Signing version: you signed with V2, but the key accepts only V1 signatures.	Sign with V1, or move the key to V2, as described in Which version does my key use?
Requests fail from one server, or after a machine wakes from sleep.	Clock skew: your timestamp is too far from the server’s time.	Synchronize your clock with NTP.
Requests without a query string work, but requests with one fail.	Query mismatch: the signed request target differs from the one you sent, often in its percent-encoding.	Build the path and query string once, and use it to sign and to send.
Requests without a body work, but requests with one fail.	Body mismatch: the signed body differs from the bytes you sent.	Serialize the body once, and send that same string. In Python, send it with `data=`, not `json=`.
A retry or a concurrent copy of a request fails, though the original went through.	Replayed request: the request exactly repeats an earlier one.	Sign every request and every retry with a new timestamp, as described in Retries and duplicate requests.
You get `403 Forbidden`.	Access denied: the key is valid, but it lacks a scope the endpoint needs, the request comes from an IP address that isn’t in the key’s IP Whitelist, or the key can’t act on the account in the path.	Check the key’s scopes and IP Whitelist in Payward Console, and the account ID you call.
You get `400 Bad Request` instead of `401 Unauthorized`.	Both signing headers: the request sends `API-Nonce` as well as `API-Timestamp`.	Send only `API-Timestamp`.

Introduction

Testing

Market data

Accounts

Verifications

Trade

Earn

Payments

Prerequisites

Authentication parameters

Which version does my key use?

Setting the `API-Key` parameter

Setting the `API-Timestamp` parameter

Setting the `API-Sign` parameter

Algorithm steps

Examples

Test vectors

`GET` with a query string and no body

`POST` with a body and no query string

Complete request example

Query parameters in signature

Request body in signature

Retries and duplicate requests

Troubleshooting

​Prerequisites

​Authentication parameters

​Which version does my key use?

​Setting the API-Key parameter

​Setting the API-Timestamp parameter

​Setting the API-Sign parameter

​Algorithm steps

​Examples

​Test vectors

​GET with a query string and no body

​POST with a body and no query string

​Complete request example

​Query parameters in signature

​Request body in signature

​Retries and duplicate requests

​Troubleshooting

Prerequisites

Authentication parameters

Which version does my key use?

Setting the `API-Key` parameter

Setting the `API-Timestamp` parameter

Setting the `API-Sign` parameter

Algorithm steps

Examples

Test vectors

`GET` with a query string and no body

`POST` with a body and no query string

Complete request example

Query parameters in signature

Request body in signature

Retries and duplicate requests

Troubleshooting