> ## Documentation Index
> Fetch the complete documentation index at: https://docs-polymarket-us.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Card title="Generate API Keys" icon="key" href="https://polymarket.us/developer">
  Visit the developer portal to generate your Ed25519 API keys. Your private key will be shown only once.
</Card>

## 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

```bash theme={null}
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

```python theme={null}
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](https://polymarket.us/developer)** 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

<Warning>
  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.
</Warning>

## 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