Authentication

API key lifecycle — generate, use, rotate, and revoke keys.

Authentication

All API requests require an API key. Keys are free to generate and come in three scopes.

Key Scopes

Scope	Rate Limit	Permissions
read	1,000 req/min	GET requests only
write	2,000 req/min	GET, POST, PUT, DELETE
admin	5,000 req/min	All endpoints

New keys default to read scope unless specified otherwise.

Generate a Key

curl -X POST https://api.gimme.fast/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trading-bot", "scope": "read"}'

Response

{
  "id": "uuid",
  "key": "gf_a1b2c3d4e5f67890abcdef1234567890",
  "name": "my-trading-bot",
  "scope": "read",
  "rate_limit": 1000,
  "message": "Save this key — it cannot be retrieved again."
}

The raw API key is shown once. We store a SHA-256 hash — if you lose the key, generate a new one.

Using Your Key

Three ways to pass the key, in order of priority:

X-API-Key header (recommended)

curl https://api.gimme.fast/v1/markets \
  -H "X-API-Key: gf_your_key_here"

SDK Usage

TypeScript

import { GimmeClient } from "@gimme-fast/sdk";

const client = new GimmeClient({ apiKey: "gf_your_key_here" });
const markets = await client.markets.list({ active: true });

WebSocket Authentication

Pass your key as a query parameter when connecting:

wss://ws.gimme.fast/ws?api_key=gf_your_key_here

WebSocket connections don’t count against your per-minute rate limit. Only REST requests do.

Rotate a Key

Atomically generates a new key and revokes the old one. Zero downtime — the new key is active before the old one is revoked.

curl -X POST https://api.gimme.fast/v1/keys/KEY_ID/rotate \
  -H "X-API-Key: gf_your_admin_key"

Response

{
  "id": "new-uuid",
  "key": "gf_new_key_here",
  "message": "Old key has been revoked. Save the new key."
}

Key rotation requires admin scope. Use it for scheduled credential rotation or when a key might be compromised.

Revoke a Key

Permanently deactivates a key. Requests using the revoked key will receive 401 Unauthorized.

curl -X DELETE https://api.gimme.fast/v1/keys/KEY_ID \
  -H "X-API-Key: gf_your_admin_key"

Key Format

All API keys follow the format gf_ + 32 hexadecimal characters (35 characters total):

gf_a1b2c3d4e5f67890abcdef1234567890

Requests with malformed keys are rejected before any database lookup.

Security Details

• Keys are stored as SHA-256 hashes — the raw key is never persisted
• Every request is logged with the key ID (not the key itself) for audit purposes
• Failed auth attempts are tracked per IP
• IPs with excessive failed attempts may be temporarily blocked