🔐Private API Access

Authenticated Routes

Signed API request are required when interacting with:

• /v1/balances/*

• /v1/users/*

• /v1/payouts/*

When generating an API Client key, you’ll receive:

• Public Key (Base58) – stored by Swapped

• Private Key (Base58, 32 bytes) – used to sign requests

⚠️ Your Commerce API Client private key is never stored by Swapped. If lost, it cannot be recovered — generate a new key instead.

Signing Requests

Every signed API request must include a signature generated from a canonical string. This canonical string is a strict, concatenated sequence of values from the request — no separators, no whitespace, and no JSON formatting.

Canonical String Format

{METHOD}{PATH}{TIMESTAMP}{IDEMPOTENCY_KEY}{BODY_SHA256}

Component Breakdown

Component	Description	Example Value	Included Exactly As
METHOD	Uppercase HTTP method	POST	"POST"
PATH	Full request path (no domain, no query params)	/v1/payouts	"/v1/payouts"
TIMESTAMP	Date.now() in milliseconds	1733359952000	"1733359952000"
IDEMPOTENCY_KEY	UUID generated per request	bcd1f714-66e8-49f2-8c7d-d21afa474ef7	"bcd1f714-66e8-49f2-8c7d-d21afa474ef7"
BODY_SHA256	Hex-encoded SHA-256 hash of raw request body (empty string if no body)	2b7df2035a…	"2b7df2035a..."

Important: These fields are concatenated directly — no spaces, newlines, or separators.

---

Example Canonical String

Raw values

Field	Value
METHOD	POST
PATH	/v1/payouts
TIMESTAMP	1733359952000
IDEMPOTENCY_KEY	bcd1f714-66e8-49f2-8c7d-d21afa474ef7
BODY_SHA256	2b7df2035a...

Concatenated canonical string:

POST/v1/payouts1733359952000bcd1f714-66e8-49f2-8c7d-d21afa474ef72b7df2035a...

---

Notes and Tips

• PATH must not include domain or query string (for example, use /v1/payouts, not https://api.example.com/v1/payouts?foo=bar)

• BODY_SHA256 must hash the exact raw body bytes and extra whitespace or comments will change the signature

• IDEMPOTENCY_KEY is required even for GET requests

• TIMESTAMP must match the value in X-Sign-Timestamp

Header	Description
X-API-Key	Your public key
X-Signature	Base64 signature generated with your private key
X-Sign-Timestamp	Date.now() in milliseconds
X-Idempotency-Key	Unique UUID per request

Below are some language specific examples for generating the X-Signature:

Javascript

const crypto = require('crypto');
const axios = require('axios');
const { sha512 } = require('@noble/hashes/sha2');
const bs58 = (await import('bs58')).default;
const ed25519 = await import('@noble/ed25519');
ed25519.etc.sha512Sync = (...args) =>
  sha512(ed25519.etc.concatBytes(...args));

const timestamp = Date.now();
const idempotencyKey = crypto.randomUUID();
const body = JSON.stringify(payload);
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const path = '/v1/payouts';

const canonical = [
  'POST',
  path,
  timestamp,
  idempotencyKey,
  bodyHash,
].join('');

const privateKeyBytes = bs58.decode(process.env.API_PRIV_KEY);
const messageBytes = new TextEncoder().encode(canonical);
const signatureBytes = ed25519.sign(messageBytes, privateKeyBytes);
const signatureB64 = Buffer.from(signatureBytes).toString('base64');

await axios.post(`https://pay-api.swapped.com${path}`, payload, {
  headers: {
    'X-API-Key': process.env.API_PUB_KEY,
    'X-Signature': signatureB64,
    'X-Sign-Timestamp': String(timestamp),
    'X-Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  }
});

Python

PHP

Our Developer Postman collection is also configured to sign requests after you configure your keys.