Authentication

Overview

This page describes how Polyblock's backend authenticates with Polymarket APIs. End users don't interact with this directly — they use email/password authentication and Polyblock handles API authentication automatically.

Authentication Flow

Polyblock uses custodial wallets to authenticate with Polymarket APIs:

1. Custodial Wallet Creation

When a user creates an account, Polyblock automatically generates a custodial wallet and stores the encrypted private key securely.

2. Polymarket API Credentials

Polyblock uses the custodial wallet to sign a message and generate Polymarket API credentials. These credentials are stored encrypted and used to authenticate all trading requests on behalf of the user.

API Credentials

After authentication, you receive three credentials:

API Key — A unique identifier for your account. Sent in request headers.
Secret — A private key used to sign requests. Never share this.
Passphrase — An additional security layer included in signed requests.

const credentials = {
  apiKey: "your-api-key-uuid",
  secret: "your-base64-secret",
  passphrase: "your-hex-passphrase"
}

HMAC Request Signing

Authenticated requests must include an HMAC signature:

import crypto from 'crypto'

function signRequest(secret, timestamp, method, path, body = '') {
  const message = timestamp + method + path + body
  const hmac = crypto.createHmac('sha256', Buffer.from(secret, 'base64'))
  hmac.update(message)
  return hmac.digest('base64')
}

Request Headers

Include these headers in authenticated requests:

const headers = {
  'POLY_ADDRESS': '0xYourWalletAddress',
  'POLY_TIMESTAMP': Math.floor(Date.now() / 1000).toString(),
  'POLY_API_KEY': credentials.apiKey,
  'POLY_SIGNATURE': signedSignature,
  'POLY_PASSPHRASE': credentials.passphrase,
  'Content-Type': 'application/json'
}

POLY_ADDRESS — Your Ethereum wallet address
POLY_TIMESTAMP — Current Unix timestamp
POLY_API_KEY — Your API key
POLY_SIGNATURE — HMAC signature
POLY_PASSPHRASE — Your passphrase

Operational security for integrators

Never log raw secrets, passphrases, or full signing payloads. Rotate API credentials if a workstation is compromised or an engineer leaves the team. Prefer short-lived tokens or scoped keys where the upstream provider allows it, and store material in a secrets manager rather than plaintext on disk.

Clock skew breaks HMAC validation—sync NTP on servers that sign requests. When debugging 401s, verify method, path, and body serialization match exactly what the signer hashed; whitespace or query-string ordering bugs are common failure modes.