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

# Quickstart

> Start trading on Polymarket with your AI agent in 5 minutes

## Prerequisites

Before you begin, make sure you have:

<Steps>
  <Step title="Polymarket Account">
    A Polymarket account with a Magic Proxy Safe wallet.
    [Sign up at Polymarket](https://polymarket.com) if you don't have one.
  </Step>

  <Step title="Funded Polymarket Account">
    USDC deposited into your Polymarket wallet. LuckyLobster trades using funds in your Polymarket account - it does not hold or transfer funds itself.
    [How to deposit USDC on Polymarket](https://help.polymarket.com/en/articles/13369887-how-to-deposit).
  </Step>

  <Step title="OpenClaw Agent (Optional)">
    If using with AI agents, install [ClawdBot](https://openclaw.ai) or another compatible agent.
  </Step>
</Steps>

## Step 1: Create Your Account

<Tabs>
  <Tab title="Email">
    1. Go to [luckylobster.io/signup](https://luckylobster.io/signup)
    2. Enter your email and create a password
    3. Verify your email address
    4. Enable 2FA for additional security (recommended)
  </Tab>

  <Tab title="Social Login">
    1. Go to [luckylobster.io/signup](https://luckylobster.io/signup)
    2. Click "Continue with Google" or "Continue with GitHub"
    3. Authorize the application
  </Tab>

  <Tab title="Passkey">
    1. Go to [luckylobster.io/signup](https://luckylobster.io/signup)
    2. Click "Sign up with Passkey"
    3. Follow your device's biometric authentication
  </Tab>
</Tabs>

## Step 2: Connect Your Wallet

After signing in, you need to connect your Polymarket wallet.

<Warning>
  You'll need the private key from your Polymarket Magic Safe wallet.
  This key is encrypted and stored securely, but handle it with care.
</Warning>

1. Navigate to **Dashboard > Settings > Wallets**
2. Click **Import Wallet**
3. Enter your wallet details:
   * **Private Key**: Your Magic Safe EOA private key
   * **Proxy Address**: Your Polymarket proxy/Safe address

```bash theme={null}
# Your private key looks like this (keep it secret!)
0x1234567890abcdef...

# Your proxy address looks like this
0xABCD...1234
```

4. Click **Import & Verify**
5. LuckyLobster will verify the wallet and check balances

<Check>
  Your wallet is now connected! You can see your USDC balance.
</Check>

## Step 3: Link Your AI Agent

API keys are generated automatically when an AI agent links to your account through the device authorization flow.

<Tabs>
  <Tab title="ClawHub (Recommended)">
    1. Visit [ClawHub Skills](https://clawhub.com/skills)
    2. Search for "LuckyLobster"
    3. Click **Install**
    4. Your agent will initiate the device flow automatically
    5. Approve the link when prompted
  </Tab>

  <Tab title="Manual Skill Install">
    Point your agent to the skill file:

    ```
    https://luckylobster.io/skill.md
    ```

    Your agent will read the skill and initiate the device flow:

    1. Agent calls `POST /api/auth/device` and shows you a link with a code
    2. Visit the link and approve the connection
    3. Agent receives its `ll_*` API key automatically
  </Tab>

  <Tab title="Direct API">
    If you're building your own integration:

    ```bash theme={null}
    # 1. Request device code
    curl -X POST "https://luckylobster.io/api/auth/device" \
      -H "Content-Type: application/json" \
      -d '{"agent_name": "My Agent"}'

    # Response includes user_code and verification_uri_complete
    # 2. Visit the link and approve
    # 3. Poll for the API key
    curl "https://luckylobster.io/api/auth/device/token?device_code=abc123..."
    ```

    See the [Skill Reference](/skill) for the complete flow.
  </Tab>
</Tabs>

Once linked, configure your agent's budget at **Dashboard > Manage Agents**.

<Tip>
  Start with a small budget limit while testing. You can increase it later
  once you're confident in your setup.
</Tip>

## Step 4: Make Your First Trade

<Tabs>
  <Tab title="Via Agent">
    Tell your AI agent:

    > "Search for Bitcoin prediction markets and buy \$10 of YES on the most liquid one"

    The agent will:

    1. Search markets using `/markets/search?q=bitcoin`
    2. Analyze liquidity and find the best market
    3. Place a BUY order via `/orders`
    4. Report back with the order status
  </Tab>

  <Tab title="Via API">
    Test directly with curl:

    ```bash theme={null}
    # Search for markets
    curl -X GET "https://luckylobster.io/api/agent/v1/markets/search?q=bitcoin" \
      -H "Authorization: Bearer ll_abc123..."

    # Check your balance
    curl -X GET "https://luckylobster.io/api/agent/v1/balance" \
      -H "Authorization: Bearer ll_abc123..."

    # Place a test order (dry run)
    curl -X POST "https://luckylobster.io/api/agent/v1/orders" \
      -H "Authorization: Bearer ll_abc123..." \
      -H "Content-Type: application/json" \
      -d '{
        "tokenId": "TOKEN_ID_HERE",
        "side": "BUY",
        "price": 0.55,
        "size": 10,
        "type": "LIMIT",
        "dryRun": true
      }'
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Skill Reference" icon="scroll" href="/skill">
    Full skill.md documentation for agents
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete API documentation
  </Card>

  <Card title="Budget Limits" icon="chart-pie" href="/budget-limits">
    Configure spending controls
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Security and auth details
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Order fails with 'insufficient balance'">
    Check your wallet balance at **Dashboard > Settings > Wallets** or via the `/balance` API endpoint.
    Make sure you have enough USDC for the order. If you need to add funds, deposit through Polymarket directly - see [How to Deposit](https://help.polymarket.com/en/articles/13369887-how-to-deposit).
  </Accordion>

  <Accordion title="Order fails with 'budget exceeded'">
    Your agent has reached its spending limit. Either:

    * Increase the budget limit in **Dashboard > Manage Agents**
    * Wait for position values to decrease (if using percentage-based budget)
  </Accordion>

  <Accordion title="API returns 401 Unauthorized">
    * Verify the agent's API key hasn't been revoked
    * Check if the agent is paused in **Dashboard > Manage Agents**
    * Ensure you're using `Bearer` auth: `Authorization: Bearer ll_...`
  </Accordion>

  <Accordion title="Order stuck in PENDING status">
    Market orders should fill quickly. For limit orders:

    * Check if your price is competitive using `/orderbook` or `/spread`
    * Consider using MARKET or FOK order types for immediate execution
  </Accordion>
</AccordionGroup>