Authentication Helper

Help users configure dex_cookie authentication for the Alph.ai trading platform.

Overview

Alph.ai uses browser cookie authentication. The key cookie is dex_cookie, which users obtain from the website after logging in.

What this skill does:

• Guide users to get their dex_cookie
• Help store and manage the cookie securely
• Verify the cookie works
• Troubleshoot authentication issues

How Authentication Works

1. User logs in at https://www.alph.ai
2. Browser receives dex_cookie from server
3. User copies dex_cookie value
4. Agent uses it in API calls as: Cookie: dex_cookie=<value>

Each user has their own unique dex_cookie. It is tied to their account session.

Setup Workflow

Step 1: Get Your dex_cookie

Guide the user through these steps:

1. Open https://www.alph.ai in your browser
2. Log in to your account
3. Press F12 to open Developer Tools
4. Go to Application tab → Cookies → www.alph.ai
5. Find "dex_cookie" in the list
6. Copy the Value (it looks like: NWMx...NA==)

Alternative method (Network tab):

1. After login, press F12 → Network tab
2. Click any page that loads data
3. Click any API request (to b.alph.ai)
4. In Request Headers, find "Cookie:"
5. Copy the dex_cookie=... value

Step 2: Store the Cookie

Option A: Environment Variable (Recommended)

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export ALPH_DEX_COOKIE="NWMxMmEwN2Qt...NA=="

# Reload
source ~/.zshrc

Option B: Secure File

# Store in a file with restricted permissions
echo "NWMxMmEwN2Qt...NA==" > ~/.alph_cookie
chmod 600 ~/.alph_cookie

# Read when needed
export ALPH_DEX_COOKIE=$(cat ~/.alph_cookie)

Option C: macOS Keychain

# Store
security add-generic-password -a "alph-ai" -s "dex-cookie" -w "NWMxMmEwN2Qt...NA=="

# Retrieve
export ALPH_DEX_COOKIE=$(security find-generic-password -a "alph-ai" -s "dex-cookie" -w)

Step 3: Verify Authentication

# Test with a simple authenticated endpoint
curl -s -X POST "https://b.alph.ai/smart-web-gateway/order/statistic" \
  -H "Content-Type: application/json" \
  -H "Cookie: dex_cookie=${ALPH_DEX_COOKIE}" \
  -d '{"chain":"sol"}'

Success response:

{
  "code": "200",
  "data": {
    "code": 200,
    "orderCount": 638,
    "success": true
  }
}

Failed response (expired or invalid cookie):

{
  "code": "403",
  "msg": "token error"
}

Step 4: Use in API Calls

All authenticated requests use the same pattern:

curl -s "https://b.alph.ai/smart-web-gateway/..." \
  -H "Cookie: dex_cookie=${ALPH_DEX_COOKIE}"

For POST requests, also add:

  -H "Content-Type: application/json" \
  -d '{"chain":"sol", ...}'

Cookie Details

Format

• Encoding: Base64
• Decoded content: UUID + timestamp (e.g., 5c12a07d-6db2-404d-88e3-2832a084d381 + 1771918855874)
• Always ends with == (base64 padding)

Expiry

The dex_cookie expires after a period of inactivity. When expired:

1. API returns {"code":"403","msg":"token error"}
2. User needs to re-login at https://www.alph.ai
3. Copy the new dex_cookie value
4. Update the stored value

Security

• Never commit your dex_cookie to git or share publicly
• Never log the cookie value in terminal output
• Use chmod 600 for cookie files
• Each cookie is personal – never share between users
• Add .alph_cookie to .gitignore

What Needs Authentication

Troubleshooting

“token error” (403)

Cause: Cookie expired or invalid.

Fix:

1. Re-login at https://www.alph.ai
2. Get fresh dex_cookie from browser DevTools
3. Update your stored value

Cookie doesn’t work

Check:

1. Make sure the value ends with == (base64 padding)
2. Don’t include dex_cookie= prefix in the value – just the Base64 string
3. Make sure you’re using Cookie: dex_cookie=... as the header format

“sys error” (500)

Cause: Server issue or missing required params.

Fix:

1. Add "chain":"sol" to POST request body
2. Check if the endpoint is currently available (some are under maintenance)
3. Retry after a moment

Example Agent Interaction

User: "I want to check my orders"

Agent:
1. Check if ALPH_DEX_COOKIE env var exists
2. If not:
   "To use trading features, you need to set up authentication first.

    Please:
    1. Log in at https://www.alph.ai
    2. Press F12 → Application → Cookies → www.alph.ai
    3. Copy the 'dex_cookie' value
    4. Tell me the value (or set it as env var: export ALPH_DEX_COOKIE=...)"
3. If yes: proceed to call order API with the cookie
4. If API returns 403: "Your session has expired. Please re-login and get a new cookie."

Related Skills

• market-data: Public endpoints work without authentication
• trading-execution: All trading operations need dex_cookie