Skip to main content

​
Overview

LuckyLobster uses two authentication systems:
  1. User Authentication - For accessing the dashboard (email/password, social login, passkeys)
  2. API Key Authentication - For agent/programmatic access to the trading API

​
User Authentication

​
Supported Methods

Email & Password

Traditional email/password with optional 2FA

Social Login

Google, GitHub, and more

Passkeys

Biometric authentication (Face ID, Touch ID, Windows Hello)

Magic Links

Passwordless email login

​
Two-Factor Authentication (2FA)

We strongly recommend enabling 2FA for additional security:
  1. Go to Dashboard > Settings > Security
  2. Click Enable 2FA
  3. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
  4. Enter the verification code to confirm
Save your 2FA backup codes in a secure location. You’ll need them if you lose access to your authenticator app.

​
API Key Authentication

​
Creating an API Key

  1. Navigate to Dashboard > API Keys
  2. Click Create New API Key
  3. Configure:
    • Name: Descriptive name (e.g., “ClawdBot Production”)
    • Permissions: Select required scopes
    • Budget Limit: Maximum spending allowed
    • Rate Limit: Requests per minute
    • Expiration: Optional expiry date
  4. Click Create
  5. Copy the key immediately - it’s only shown once!

​
API Key Format

ll_live_abc123xyz789defghi456...
  • Prefix: ll_live_ (production) or ll_test_ (sandbox)
  • Length: 64 characters total

​
Using API Keys

Include your API key in the Authorization header: 
curl -X GET "https://luckylobster.io/api/agent/v1/balance" \
  -H "Authorization: Bearer ll_live_your_key_here"

​
Permission Scopes

ScopeDescriptionEndpoints
readRead-only accessMarkets, balance, positions, order history
tradePlace and cancel ordersPOST /orders, DELETE /orders
redeemRedeem settled marketsPOST /settlements/redeem
adminFull account accessAll endpoints
Follow the principle of least privilege. Only grant the permissions your agent actually needs.

​
Rate Limiting

Each API key has configurable rate limits:
  • Default: 100 requests/minute
  • Headers: Check X-RateLimit-* headers in responses
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
When rate limited, you’ll receive a 429 Too Many Requests response: 
{
  "success": false,
  "error": "Rate Limited",
  "message": "Too many requests. Please wait before retrying.",
  "retryAfter": 30
}

​
Budget Limits

API keys can have spending limits:
SettingDescription
budgetLimitMaximum total USDC spend
budgetUsedAmount already spent
budgetPeriodReset period (daily, weekly, monthly, never)
Check your budget via the API: 
curl "https://luckylobster.io/api/agent/v1/budget" \
  -H "Authorization: Bearer ll_live_..."
Response: 
{
  "success": true,
  "data": {
    "limit": 1000,
    "used": 250.50,
    "remaining": 749.50,
    "period": "monthly",
    "resetsAt": "2024-02-01T00:00:00Z"
  }
}

​
Revoking API Keys

To revoke an API key:
  1. Go to Dashboard > API Keys
  2. Find the key you want to revoke
  3. Click the Revoke button
  4. Confirm the action
Revoking a key is immediate and irreversible. Any agents using that key will lose access.

​
Security Best Practices

API keys should only be used server-side or in secure agent environments. Never include them in browser JavaScript, mobile apps, or public repositories.
Create dedicated API keys for each agent or use case. This allows you to revoke access individually and track usage separately.
For temporary access, set an expiration date on your API keys. Expired keys are automatically disabled.
Start with low budget limits and increase as needed. This protects against bugs or unexpected agent behavior.
Periodically generate new keys and revoke old ones. This limits the impact of any potential key compromise.

​
Wallet Security

Your Polymarket wallet private key is protected with:
  • AES-256-GCM encryption at rest
  • Per-wallet unique IV (initialization vector)
  • Server-side only decryption during order signing
  • No client-side key exposure
The encryption key is stored securely in our infrastructure and never exposed in API responses.

​
Audit Logging

All sensitive operations are logged:
  • API key creation/revocation
  • Order placement
  • Wallet operations
  • Login attempts
  • Permission changes
Access your audit log at Dashboard > Settings > Activity Log.

​
API Reference

Auth Endpoints

Full API authentication documentation