Authentication

Authentication Scheme

Trading API uses Ed25519 signature authentication (signatureAuth).

To authenticate with the Trading API, you'll need an Ed25519 keypair (private and public keys). See the Generating Ed25519 Keypairs section below for instructions on how to generate them.

Each authenticated request must include three headers:

Header

Description

x-thegrid-signature

Base64-encoded Ed25519 signature

x-thegrid-timestamp

Unix timestamp (seconds since epoch)

x-thegrid-fingerprint

SHA256 hash of your public key (Base64-encoded)

Signature Generation Process

Construct the message: timestamp + HTTP_METHOD + request_path + body
Sign the message with your Ed25519 private key
Base64 encode the signature
Include headers in your request

Important: The request_path is the endpoint path without query parameters. Query parameters are sent with the HTTP request but are excluded from signature computation.

Signature Examples:

For a simple POST request to /api/v1/trading/orders:

Message to sign: {timestamp}POST/api/v1/trading/orders{"market_id":"market_b310e860-97cd-45eb-bdc3-5be0b79295d0","side":"buy",...}

For a GET request with query parameters like /api/v1/trading/orders?limit=10&next=eyJpZCI6Im9yZGVyX1pWRk9BR0c0SldSTlhNQ0sifQ:

Path for signature: /api/v1/trading/orders  (query string excluded)
Message to sign: {timestamp}GET/api/v1/trading/orders

Common mistake (will cause "Signature verification failed"):

# WRONG - do not include query parameters in signature
Message: 1739145600GET/api/v1/trading/orders?limit=10

Correct:

# RIGHT - only the path, no query string
Message: 1739145600GET/api/v1/trading/orders

import base64
import hashlib
import time
from nacl.signing import SigningKey

class SignatureAuth:
    def __init__(self, private_key_base64, public_key_base64):
        self.private_key = SigningKey(base64.b64decode(private_key_base64))
        public_key_bytes = base64.b64decode(public_key_base64)
        hash_obj = hashlib.sha256(public_key_bytes)
        self.fingerprint = base64.b64encode(hash_obj.digest()).decode('utf-8').rstrip('=')

    def get_headers(self, method, path, body=''):
        timestamp = str(int(time.time()))
        message = f"{timestamp}{method.upper()}{path}{body}"
        message_bytes = message.encode('utf-8')
        signature_bytes = self.private_key.sign(message_bytes).signature
        signature = base64.b64encode(signature_bytes).decode('utf-8')

        return {
            'x-thegrid-signature': signature,
            'x-thegrid-timestamp': timestamp,
            'x-thegrid-fingerprint': self.fingerprint
        }

import nacl from 'tweetnacl';
import util from 'tweetnacl-util';
import crypto from 'crypto';

class SignatureAuth {
  constructor(privateKeyBase64, publicKeyBase64) {
    this.privateKey = util.decodeBase64(privateKeyBase64);
    const publicKeyBuffer = Buffer.from(publicKeyBase64, 'base64');
    const hash = crypto.createHash('sha256').update(publicKeyBuffer).digest('base64');
    this.fingerprint = hash.replace(/=+$/, '');
  }

  getHeaders(method, path, body = '') {
    const timestamp = Math.floor(Date.now() / 1000).toString();
    const message = `${timestamp}${method.toUpperCase()}${path}${body}`;
    const messageBytes = util.decodeUTF8(message);
    const signatureBytes = nacl.sign.detached(messageBytes, this.privateKey);
    const signature = util.encodeBase64(signatureBytes);

    return {
      'x-thegrid-signature': signature,
      'x-thegrid-timestamp': timestamp,
      'x-thegrid-fingerprint': this.fingerprint
    };
  }
}

package main

import (
    "crypto/ed25519"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "strings"
    "time"
)

type SignatureAuth struct {
    privateKey  ed25519.PrivateKey
    fingerprint string
}

func NewSignatureAuth(privateKeyBase64, publicKeyBase64 string) (*SignatureAuth, error) {
    privateKey, err := base64.StdEncoding.DecodeString(privateKeyBase64)
    if err != nil {
        return nil, err
    }

    publicKey, err := base64.StdEncoding.DecodeString(publicKeyBase64)
    if err != nil {
        return nil, err
    }

    hash := sha256.Sum256(publicKey)
    fingerprint := base64.StdEncoding.EncodeToString(hash[:])
    fingerprint = strings.TrimRight(fingerprint, "=")

    return &SignatureAuth{
        privateKey:  ed25519.PrivateKey(privateKey),
        fingerprint: fingerprint,
    }, nil
}

func (a *SignatureAuth) GetHeaders(method, path, body string) map[string]string {
    timestamp := fmt.Sprintf("%d", time.Now().Unix())
    message := timestamp + strings.ToUpper(method) + path + body

    signature := ed25519.Sign(a.privateKey, []byte(message))
    signatureBase64 := base64.StdEncoding.EncodeToString(signature)

    return map[string]string{
        "x-thegrid-signature":  signatureBase64,
        "x-thegrid-timestamp":  timestamp,
        "x-thegrid-fingerprint": a.fingerprint,
    }
}

Generating Ed25519 Keypairs

To authenticate with the Trading API, you'll need an Ed25519 keypair (private and public keys). Here's how to generate them in different languages:

Generate a private key (32-byte seed)

openssl genpkey -algorithm Ed25519 -out private_key.pem

Extract the public key for adding in The Grid UI

openssl pkey -in private_key.pem -pubout -out public_key.pem

Convert private key to Base64 format for use with the API

openssl pkey -in private_key.pem -outform DER | tail -c +13 | base64

Convert public key to Base64 format for use with the API

openssl pkey -pubin -in public_key.pem -outform DER | base64

import base64
from nacl.signing import SigningKey

# Generate a new Ed25519 keypair
signing_key = SigningKey.generate()

# Get the private key (64 bytes: 32-byte seed + 32-byte public key)
private_key_bytes = bytes(signing_key)
private_key_base64 = base64.b64encode(private_key_bytes).decode('utf-8')

# Get the public key (32 bytes)
public_key_bytes = bytes(signing_key.verify_key)
public_key_base64 = base64.b64encode(public_key_bytes).decode('utf-8')

print(f"Private Key (Base64): {private_key_base64}")
print(f"Public Key (Base64): {public_key_base64}")

Note: The private key includes both the seed and public key. You can extract just the seed (first 32 bytes) if needed.

import nacl from 'tweetnacl';
import util from 'tweetnacl-util';

// Generate a new Ed25519 keypair
const keypair = nacl.sign.keyPair();

// Get the private key (64 bytes: 32-byte seed + 32-byte public key)
const privateKeyBase64 = util.encodeBase64(keypair.secretKey);

// Get the public key (32 bytes)
const publicKeyBase64 = util.encodeBase64(keypair.publicKey);

console.log(`Private Key (Base64): ${privateKeyBase64}`);
console.log(`Public Key (Base64): ${publicKeyBase64}`);

Note: The secretKey includes both the seed and public key. You can extract just the seed (first 32 bytes) if needed.

package main

import (
    "crypto/ed25519"
    "encoding/base64"
    "fmt"
)

func main() {
    // Generate a new Ed25519 keypair
    publicKey, privateKey, err := ed25519.GenerateKey(nil)
    if err != nil {
        panic(err)
    }

    // Get the private key (64 bytes: 32-byte seed + 32-byte public key)
    privateKeyBase64 := base64.StdEncoding.EncodeToString(privateKey)

    // Get the public key (32 bytes)
    publicKeyBase64 := base64.StdEncoding.EncodeToString(publicKey)

    fmt.Printf("Private Key (Base64): %s\n", privateKeyBase64)
    fmt.Printf("Public Key (Base64): %s\n", publicKeyBase64)
}

Note: The private key includes both the seed and public key. You can extract just the seed (first 32 bytes) if needed.

Important Security Notes:

Never share your private key - keep it secure and never commit it to version control
Store keys securely - use environment variables or secure key management systems
Use different keypairs for different environments (development, staging, production)
The private key format includes both the seed and public key (64 bytes total)
The public key is 32 bytes and is used to generate the fingerprint for the x-thegrid-fingerprint header

PreviousBase URLs NextRequest & Response Conventions

Last updated 11 hours ago

Was this helpful?

Good night

hashtagAuthentication Scheme

hashtagSignature Generation Process

hashtagGenerating Ed25519 Keypairs

Authentication Scheme

Signature Generation Process

Generating Ed25519 Keypairs