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)

​
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

​
How API Keys Are Created

API keys are generated through the device authorization flow when an AI agent links to your account. There is no manual “Create API Key” button - instead:
  1. Your AI agent initiates the device flow (POST /api/auth/device)
  2. You visit the link page and enter the code shown by your agent
  3. After you approve, the agent receives an ll_* API key automatically
Once linked, you manage your agents and their API keys at Dashboard > Manage Agents.
See the Skill Reference for the full device authorization flow, or the Quickstart for a step-by-step walkthrough.

​
API Key Format

ll_abc123xyz789defghi456...
  • Prefix: ll_
  • Hash: 64-character secure random string

​
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_your_key_here"

​
Permission Scopes

All linked agents receive the standard set of permissions:
ScopeDescriptionEndpoints
readRead-only accessMarkets, balance, positions, order history
tradePlace ordersPOST /orders
cancelCancel open ordersDELETE /orders
redeemRedeem settled marketsPOST /settlements/redeem

​
Rate Limiting

API keys are rate limited to protect against abuse:
  • 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

You can configure spending limits for each agent at Dashboard > Manage Agents:
SettingDescription
Fixed LimitMaximum USDC the agent can spend
Budget PercentPercentage of wallet balance the agent can use
Max Position ValueCap on total open position value
Check budget via the API: 
curl "https://luckylobster.io/api/agent/v1/budget" \
  -H "Authorization: Bearer ll_..."
Response: 
{
  "success": true,
  "data": {
    "usdc": 46.58,
    "limitedBy": "percent",
    "wallet": 93.16,
    "config": {
      "fixedLimit": null,
      "budgetPercent": 50,
      "maxPositionValue": null,
      "used": 0
    }
  }
}

​
Revoking API Keys

To revoke an agent’s API key:
  1. Go to Dashboard > Manage Agents
  2. Find the agent 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.
Start with low budget limits and increase as needed. This protects against bugs or unexpected agent behavior.
Use the pause feature in Manage Agents to temporarily disable an agent without revoking its key. You can resume it later.

​
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:
  • Agent linking/revocation
  • Order placement
  • Wallet operations
  • Login attempts

​
API Reference

Auth Endpoints

Full API authentication documentation