Skip to main content

​
Overview

This guide walks you through:
  1. Creating a Carboncopy account
  2. Generating an API key
  3. Making your first request
  4. Iterating from there

​
Step 1 — Create an account

Head to carboncopy.inc and sign in with your email. Once authenticated, connect your Polymarket wallet under Settings.

​
Step 2 — Generate an API key

Navigate to Settings → API Keys in the Dashboard, then click New Key. Configure the scopes you need — for a read-only monitoring bot, portfolio:read and traders:read are sufficient. For a bot that can follow/unfollow traders, also add traders:write.
The key secret (cc_<64 hex chars>) is shown exactly once at creation time. Copy it to your password manager or secrets store immediately.

​
Step 3 — Make your first request

Verify the API is reachable (no auth required): 
curl https://carboncopy.inc/api/v1/health

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": 1741600000000
}
Now fetch your portfolio summary using your new key: 
export CC_API_KEY="cc_your_key_here"

curl https://carboncopy.inc/api/v1/portfolio \
  -H "Authorization: Bearer $CC_API_KEY"

{
  "totalValue": 5420.75,
  "positionsValue": 1840.22,
  "currentExposure": 1840.22,
  "grossVolume": 7392.10,
  "totalVolume": 7392.10,
  "realizedPnl": 355.20,
  "unrealizedPnl": 65.30,
  "totalPnl": 420.50,
  "pnlPercentage": 8.41,
  "openPositions": 12,
  "tradersFollowing": 7
}

​
Step 4 — Follow a trader

To start copying a wallet, your key needs traders:write scope: 
curl -X POST https://carboncopy.inc/api/v1/traders \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0xAbCd1234...",
    "copyPercentage": 25,
    "maxCopyAmount": 500
  }'
This will copy 25% of every trade by 0xAbCd1234..., up to a maximum of $500 USDC per trade.

​
Step 5 — Monitor your positions

Poll open positions to track what’s currently deployed: 
curl "https://carboncopy.inc/api/v1/portfolio/positions?limit=20" \
  -H "Authorization: Bearer $CC_API_KEY"
See Pagination for iterating beyond the first page.

​
Next steps

Authentication

Learn about API key scopes and security.

API Reference

Full interactive endpoint documentation.

Errors

Handle errors gracefully in your bot.

Pagination

Iterate over large result sets with cursors.