Authentication

How to authenticate with the Retail API

All API endpoints require authentication using Ed25519 digital signatures.

• Ed25519 elliptic curve digital signature algorithm
• Request signing with private keys
• 256-bit security level (equivalent to RSA-3072 or higher)
• Required for trading, portfolio, and WebSocket endpoints

Generate API Keys

Visit the developer portal to generate your Ed25519 API keys. Your private key will be shown only once.

How It Works

Each API request must be signed with your private Ed25519 key. The signature proves that the request came from you without exposing your private key.

Signature Construction

message = timestamp + method + path
signature = Ed25519.sign(private_key, message)

Example:

timestamp = "1705420800000"
method = "GET"
path = "/v1/portfolio/positions"

message = "1705420800000GET/v1/portfolio/positions"
signature = Ed25519.sign(your_private_key, message)

Required Headers

Every authenticated request must include these three headers:

Header	Value	Description
X-PM-Access-Key	API key ID (UUID)	Your public API key identifier
X-PM-Timestamp	Unix timestamp in milliseconds	Current time when making the request
X-PM-Signature	Base64-encoded Ed25519 signature	Signature of timestamp + method + path

Example Request

GET https://api.polymarket.us/v1/portfolio/positions
X-PM-Access-Key: 550e8400-e29b-41d4-a716-446655440000
X-PM-Timestamp: 1705420800000
X-PM-Signature: 4vJ5Ij0mQ8G1jR3L...base64...

Python Example

import time
import base64
from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.hazmat.primitives import serialization
import requests

# Load your Ed25519 private key (64 bytes, base64-encoded)
private_key_base64 = "YOUR_BASE64_PRIVATE_KEY"
private_key_bytes = base64.b64decode(private_key_base64)

# Parse the Ed25519 private key
private_key = ed25519.Ed25519PrivateKey.from_private_bytes(
    private_key_bytes[:32]  # First 32 bytes are the seed
)

# API key ID from developer portal
api_key_id = "550e8400-e29b-41d4-a716-446655440000"

# Prepare request
method = "GET"
path = "/v1/portfolio/positions"
timestamp = str(int(time.time() * 1000))  # Milliseconds

# Sign the request
message = f"{timestamp}{method}{path}"
signature = private_key.sign(message.encode('utf-8'))
signature_base64 = base64.b64encode(signature).decode('utf-8')

# Make the request
headers = {
    "X-PM-Access-Key": api_key_id,
    "X-PM-Timestamp": timestamp,
    "X-PM-Signature": signature_base64
}

response = requests.get(
    f"https://api.polymarket.us{path}",
    headers=headers
)

print(response.json())

Getting Started

1. Visit the web portal to generate your API keys
2. Receive your API key ID and private key - the private key is shown only once
3. Store your private key securely - you cannot retrieve it later
4. Sign each request using the Ed25519 signature method above

Key Structure

Your Ed25519 private key is 64 bytes (base64-encoded):

• Bytes 0-31: Seed (used to derive the key pair)
• Bytes 32-63: Public key

The public key is stored in our database and used to verify your signatures. The private key never leaves your possession.

Security Features

• Immediate revocation: Keys can be revoked instantly via the developer portal
• No token expiration: Keys remain valid until explicitly revoked
• Fast verification: Ed25519 signature verification is extremely fast
• Kalshi-compatible: Same algorithm used by other prediction market platforms

API Key Security

• Store keys securely - treat them like passwords
• Never commit keys to version control - use environment variables
• Rotate keys regularly - generate new keys periodically
• Revoke compromised keys immediately - use the developer portal
• Use separate keys for different environments - dev, staging, production
• Private key shown only once - save it immediately when generated

Anyone with your private key can access your account and trade on your behalf. The private key is shown only once during generation and cannot be retrieved later. Store it securely immediately.

Timestamp Validation

Requests must have a timestamp within 30 seconds of the server time to prevent replay attacks. If your request fails with a timestamp error:

1. Ensure your system clock is synchronized (use NTP)
2. Generate a fresh timestamp for each request
3. Check that you’re using milliseconds, not seconds