Authentication

All funder API requests use API Key + HMAC-SHA256 signature authentication. This provides request-level integrity verification without token refresh complexity.

Required Headers

Every request must include three headers:

Header	Description
`X-API-Key`	Your API key (identifies your funder account)
`X-Timestamp`	Unix timestamp in seconds (replay protection)
`X-Signature`	HMAC-SHA256 signature of the request

Computing the Signature

The signature is computed over the concatenation of the timestamp and request body:

message = timestamp + "." + request_body
signature = HMAC-SHA256(message, your_hmac_secret)

Node.js Example

import crypto from 'crypto';

function signRequest(body, hmacSecret) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const message = `${timestamp}.${JSON.stringify(body)}`;
  const signature = crypto
    .createHmac('sha256', hmacSecret)
    .update(message)
    .digest('hex');

  return {
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  };
}

Python Example

import hmac
import hashlib
import json
import time

def sign_request(body: dict, hmac_secret: str) -> dict:
    timestamp = str(int(time.time()))
    message = f"{timestamp}.{json.dumps(body, separators=(',', ':'))}"
    signature = hmac.new(
        hmac_secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    return {
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    }

Replay Protection

Requests with timestamps older than 5 minutes are rejected. Ensure your server's clock is synchronized (NTP).

API Key Scopes

API keys are issued with specific scopes:

Scope	Description
`offers:create`	Create new offers
`offers:update`	Replace or patch existing offers
`offers:delete`	Revoke offers

Error Responses

Status	Error Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key
401	`SIGNATURE_INVALID`	HMAC signature verification failed
401	`TIMESTAMP_EXPIRED`	Timestamp older than 5 minutes
403	`INSUFFICIENT_SCOPE`	API key lacks required scope
429	`RATE_LIMITED`	Too many requests