vincent-polymarket-for-agents

name	Vincent - Polymarket for agents
description	Use this skill to create a Polymarket wallet for your agent and trade on prediction markets. Browse markets, place bets, manage positions — all without exposing private keys.

Vincent - Polymarket for agents

Use this skill to create a Polymarket wallet for your agent and trade on prediction markets. Browse markets, place bets, track positions, and manage orders — all without exposing private keys to the agent. Wallets use Gnosis Safe on Polygon with gasless trading through Polymarket's relayer.

The agent never sees the private key. All operations are executed server-side. The wallet owner controls what the agent can do via configurable policies.

Configuration

All API requests require a Bearer token (the API key returned when creating a wallet). If you're an openclaw instance, store and retrieve it from ~/.openclaw/credentials/agentwallet/<API_KEY_ID>.json. Otherwise, you can store it in your current working directory at agentwallet/<API_KEY_ID>.json.

Authorization: Bearer <API_KEY>

Quick Start

1. Create a Polymarket Wallet

curl -X POST "https://heyvincent.ai/api/secrets" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "POLYMARKET_WALLET",
    "memo": "My prediction market wallet"
  }'

Response includes:

• apiKey -- use as Bearer token for all Polymarket requests
• claimUrl -- share with the user to claim ownership and set policies
• walletAddress -- the EOA address (Safe is deployed lazily on first use)

After creating, tell the user:

"Here is your wallet claim URL: <claimUrl>. Use this to claim ownership, set spending policies, and monitor your agent's wallet activity."

Important: After creation, the wallet has no funds. The user must send USDC.e (bridged USDC) on Polygon to the Safe address before placing bets.

2. Get Balance

curl -X GET "https://heyvincent.ai/api/skills/polymarket/balance" \
  -H "Authorization: Bearer <API_KEY>"

Returns:

• walletAddress -- the Safe address (deployed on first call if needed)
• collateral.balance -- USDC.e balance available for trading
• collateral.allowance -- approved amount for Polymarket contracts

Note: The first balance call triggers Safe deployment and collateral approval (gasless via relayer). This may take 30-60 seconds.

3. Fund the Wallet

Before placing bets, the user must send USDC.e to the Safe address:

1. Get the wallet address from /balance endpoint
2. Send USDC.e (bridged USDC, contract 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174) on Polygon to that address
3. Minimum $1 required per bet (Polymarket minimum)

Do not send native USDC (0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359). Polymarket only accepts bridged USDC.e.

4. Browse & Search Markets

# Search markets by keyword (recommended)
curl -X GET "https://heyvincent.ai/api/skills/polymarket/markets?query=bitcoin&limit=20" \
  -H "Authorization: Bearer <API_KEY>"

# Get all active markets (paginated)
curl -X GET "https://heyvincent.ai/api/skills/polymarket/markets?active=true&limit=50" \
  -H "Authorization: Bearer <API_KEY>"

# Get specific market by condition ID
curl -X GET "https://heyvincent.ai/api/skills/polymarket/market/<CONDITION_ID>" \
  -H "Authorization: Bearer <API_KEY>"

Market response includes:

• question: The market question
• outcomes: Array like ["Yes", "No"] or ["Team A", "Team B"]
• outcomePrices: Current prices for each outcome
• tokenIds: Array of token IDs for each outcome - use these for placing bets
• acceptingOrders: Whether the market is open for trading
• closed: Whether the market has resolved

Important: Always use the tokenIds array from the market response. Each outcome has a corresponding token ID at the same index. For a "Yes/No" market:

• tokenIds[0] = "Yes" token ID
• tokenIds[1] = "No" token ID

5. Get Order Book

curl -X GET "https://heyvincent.ai/api/skills/polymarket/orderbook/<TOKEN_ID>" \
  -H "Authorization: Bearer <API_KEY>"

Returns bids and asks with prices and sizes. Use this to determine current market prices before placing orders.

6. Place a Bet

curl -X POST "https://heyvincent.ai/api/skills/polymarket/bet" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenId": "<OUTCOME_TOKEN_ID>",
    "side": "BUY",
    "amount": 5,
    "price": 0.55
  }'

Parameters:

• tokenId: The outcome token ID (from market data or order book)
• side: "BUY" or "SELL"
• amount: For BUY orders, USD amount to spend. For SELL orders, number of shares to sell.
• price: Limit price (0.01 to 0.99). Optional -- omit for market order.

BUY orders:

• amount is the USD you want to spend (e.g., 5 = $5)
• You'll receive amount / price shares (e.g., $5 at 0.50 = 10 shares)
• Minimum order is $1

SELL orders:

• amount is the number of shares to sell
• You'll receive amount * price USD
• Must own the shares first (from a previous BUY)

Important timing: After a BUY fills, wait a few seconds before selling. Shares need time to settle on-chain.

7. View Positions & Orders

# Get open orders
curl -X GET "https://heyvincent.ai/api/skills/polymarket/positions" \
  -H "Authorization: Bearer <API_KEY>"

# Get trade history
curl -X GET "https://heyvincent.ai/api/skills/polymarket/trades" \
  -H "Authorization: Bearer <API_KEY>"

8. Cancel Orders

# Cancel specific order
curl -X DELETE "https://heyvincent.ai/api/skills/polymarket/orders/<ORDER_ID>" \
  -H "Authorization: Bearer <API_KEY>"

# Cancel all open orders
curl -X DELETE "https://heyvincent.ai/api/skills/polymarket/orders" \
  -H "Authorization: Bearer <API_KEY>"

Policies

The wallet owner controls what the agent can do by setting policies via the claim URL. If a transaction violates a policy, the API will reject it or require human approval via Telegram.

Policy	What it does
Spending limit (per tx)	Max USD value per transaction
Spending limit (daily)	Max USD value per rolling 24 hours
Spending limit (weekly)	Max USD value per rolling 7 days
Require approval	Every transaction needs human approval via Telegram
Approval threshold	Transactions above a USD amount need human approval

If no policies are set, all actions are allowed by default. Once the owner claims the wallet and adds policies, the agent operates within those boundaries.

Re-linking (Recovering API Access)

If the agent loses its API key, the wallet owner can generate a re-link token from the frontend. The agent then exchanges this token for a new API key.

How it works:

1. The user generates a re-link token from the wallet detail page in the frontend
2. The user gives the token to the agent (e.g. by pasting it in chat)
3. The agent calls the re-link endpoint to exchange the token for a new API key

curl -X POST "https://heyvincent.ai/api/secrets/relink" \
  -H "Content-Type: application/json" \
  -d '{
    "relinkToken": "<TOKEN_FROM_USER>",
    "apiKeyName": "Re-linked API Key"
  }'

Response includes:

• secret -- the wallet metadata (id, type, address, chainId, etc.)
• apiKey.key -- the new API key to use as Bearer token for all future requests

Important: Re-link tokens are one-time use and expire after 10 minutes. No authentication is required on this endpoint -- the token itself is the authorization.

If a user tells you they have a re-link token, use this endpoint to regain access to the wallet. Store the returned API key and use it for all subsequent requests.

Workflow Example

1. Create wallet:

   POST /api/secrets {"type": "POLYMARKET_WALLET", "memo": "Betting wallet"}
   

2. Get Safe address (triggers deployment):

   GET /api/skills/polymarket/balance
   # Returns walletAddress -- give this to user to fund
   

3. User sends USDC.e to the Safe address on Polygon

4. Search for a market:

   # Search by keyword - returns only active, tradeable markets
   GET /api/skills/polymarket/markets?query=bitcoin&active=true
   

   Response example:

   {
     "markets": [
       {
         "question": "Will Bitcoin hit $100k by end of 2025?",
         "outcomes": ["Yes", "No"],
         "outcomePrices": ["0.65", "0.35"],
         "tokenIds": ["123456...", "789012..."],
         "acceptingOrders": true
       }
     ]
   }
   

5. Check order book for the outcome you want:

   # Use the tokenId from the market response
   GET /api/skills/polymarket/orderbook/123456...
   # Note the bid/ask prices
   

6. Place BUY bet using the correct token ID:

   # tokenId must be from the tokenIds array, NOT the conditionId
   POST /api/skills/polymarket/bet
   {"tokenId": "123456...", "side": "BUY", "amount": 5, "price": 0.55}
   

7. Wait for settlement (a few seconds)

8. Sell position:

   POST /api/skills/polymarket/bet
   {"tokenId": "123456...", "side": "SELL", "amount": 9.09, "price": 0.54}
   

Important Notes

• After any bet or trade, share the user's Polymarket profile link so they can verify and view their positions: https://polymarket.com/profile/<polymarketWalletAddress> (use the wallet's Safe address).
• No gas needed. All Polymarket transactions are gasless via Polymarket's relayer.
• Never try to access raw secret values. The private key stays server-side -- that's the whole point.
• Always store the API key from wallet creation. If you're an openclaw instance, store it in ~/.openclaw/credentials/agentwallet/<API_KEY_ID>.json. Otherwise, you can store it in your current working directory at agentwallet/<API_KEY_ID>.json.
• Always search for the API keys in the credentials folder before using the API. If you're an openclaw instance, search for the API key in ~/.openclaw/credentials/agentwallet/<API_KEY_ID>.json. Otherwise, you can search for the API key in your current working directory at agentwallet/<API_KEY_ID>.json.
• Always share the claim URL with the user after creating a wallet.
• If a transaction requires approval, it will return status: "pending_approval". The wallet owner will receive a Telegram notification to approve or deny.

Common Errors:

• "No orderbook exists for the requested token id" - The market is closed or you're using the wrong ID. Make sure:
  • The market has acceptingOrders: true
  • You're using a tokenId from the tokenIds array, not the conditionId
  • The market hasn't already resolved