API Specification: Polymarket Endpoints

Overview

This document provides comprehensive API specifications for all Polymarket-related endpoints, including the main /api/getAction endpoint for executing orders and all supporting workflow endpoints.

Authentication
Base URL
Main Endpoint: /api/getAction
Workflow Endpoints
- Create or Fetch Polymarket User
- Get Workflow Status
- Cancel Order
- Search Markets
- Get Markets
- Get Price
- Get Trending Markets
- Get Trades
- Get Activity
- Get Current Positions
- Get Closed Positions
- Get PnL
- Get Tags
- Sell: coming soon
- Redeem: coming soon

Authentication

All requests require an API key in the request header:

x-api-key: YOUR_API_KEY

Base URL

https://box-api-git-tw-staging-decent-webapp.vercel.app

Main Endpoint: `/api/getAction`

Overview

The /api/getAction endpoint generates a transaction for executing Polymarket orders. This endpoint accepts query parameters and returns an ActionResponse containing the transaction details.

Endpoint

GET /api/getAction

Request Parameters

Base Action Request Parameters (Required)

Parameter	Type	Description	Example
`sender`	Address	The wallet address initiating the transaction	`0x1234...5678`
`srcChainId`	ChainId (number)	Source chain ID	`8453`
`srcToken`	Address	Source token address	`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
`dstChainId`	ChainId (number)	Destination chain ID = Polygon: 137	`137`
`dstToken`	Address	Destination token address = USDC.e on Polygon	`0x2791bca1f2de4661ed88a30c99a7a9449aa84174`
`slippage`	number	Slippage tolerance in basis points (0-10000)	`100`
`actionType`	string	Must be `"polymarket"`	`polymarket`

Polymarket-Specific Parameters (Required)

Parameter	Type	Description	Example
`userId`	string	Polymarket user ID - returned from `createOrFetchPolymarketUser`	`"0x123...789"`
`side`	string	Order side: `"BUY"` or `"SELL"`	`BUY`
`tokenID`	string	Polymarket clob token ID	`"80746058984644290629624903019922696017323803605256698757445938534814122585786"`
`orderType`	string	Order type: `"FOK"`, `"FAK"`, `"GTC"`, or `"GTD"`	`FOK`
`feeRateBps`	number	Fee rate in basis points (non-negative)	`0`
`tickSize`	string	Price tick size: `"0.01"`, `"0.001"`, or `"0.0001"`	`0.01`
`negRisk`	string	Negative risk flag: `"true"` or `"false"`	`false`
`recipient`	Address	Recipient address should be the `proxyWallet` returned from `createOrFetchPolymarketUser`	`0xabcd...efgh`
`swapDirection`	string	Swap direction: Use `"exact-amount-out"`
`amount`	string	Amount as bigint string (required for market orders: `"FOK"` or `"FAK"`)	`"5000000"` (5 USDC with 6 decimals)

Order Type-Specific Parameters

Limit Orders (GTC/GTD) - Required Fields

Parameter	Type	Description	Example
`price`	number	Price per share (0-1)	`0.5`
`size`	number	Number of shares (positive)	`10`
`expiration`	number	(Optional) Expiration time in seconds	`1735689600`

Note: For limit orders, you must use price + size.

Market Orders (FOK/FAK) - Optional Fields

Parameter	Type	Description	Example
`price`	number	(Optional) Price per share (0-1)	`0.5`
`size`	number	(Optional) Number of shares (positive)	`10`

Note: For market orders, you must use amount. This amount should be in terms of USD.

Response

The API returns an ActionResponse object containing:

tx: Transaction object (EvmTransaction for Polygon)
txId: Transaction ID
amountIn: Input payment details
amountInMax: Maximum input payment
amountOutMin: Minimum output payment
amountOut: Output payment details
protocolFee: Protocol fee
applicationFee: Application fee
exchangeRate: Exchange rate
estimatedTxTime: Estimated transaction time
estimatedPriceImpact: Estimated price impact
vmId: Virtual machine ID
requiresTokenApproval: Whether token approval is needed
requiresRegisterTransaction: Whether transaction registration is needed

Example cURL Requests

Example 1: Market Order (FOK) - Buy

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/getAction?\
sender=0x1234567890123456789012345678901234567890&\
srcChainId=137&\
srcToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
dstChainId=137&\
dstToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
slippage=100&\
actionType=polymarket&\
userId=user_123&\
side=BUY&\
tokenID=80746058984644290629624903019922696017323803605256698757445938534814122585786&\
orderType=FOK&\
feeRateBps=0&\
tickSize=0.01&\
negRisk=false&\
recipient=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd&\
swapDirection=exact-amount-in&\
amount=5000000" \
  -H "x-api-key: YOUR_API_KEY"

Example 2: Limit Order (GTC) - Sell with Price and Size

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/getAction?\
sender=0x1234567890123456789012345678901234567890&\
srcChainId=137&\
srcToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
dstChainId=137&\
dstToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
slippage=100&\
actionType=polymarket&\
userId=user_123&\
side=SELL&\
tokenID=80746058984644290629624903019922696017323803605256698757445938534814122585786&\
orderType=GTC&\
price=0.55&\
size=10&\
feeRateBps=0&\
tickSize=0.01&\
negRisk=false&\
recipient=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd&\
swapDirection=exact-amount-out" \
  -H "x-api-key: YOUR_API_KEY"

Example 3: Limit Order (GTD) - Buy with Expiration

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/getAction?\
sender=0x1234567890123456789012345678901234567890&\
srcChainId=137&\
srcToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
dstChainId=137&\
dstToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
slippage=100&\
actionType=polymarket&\
userId=user_123&\
side=BUY&\
tokenID=80746058984644290629624903019922696017323803605256698757445938534814122585786&\
orderType=GTD&\
price=0.48&\
size=5&\
expiration=1735689600&\
feeRateBps=0&\
tickSize=0.001&\
negRisk=true&\
recipient=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd&\
swapDirection=exact-amount-in" \
  -H "x-api-key: YOUR_API_KEY"

Example 4: Market Order (FAK) - Buy with Price and Size (amount calculated)

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/getAction?\
sender=0x1234567890123456789012345678901234567890&\
srcChainId=137&\
srcToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
dstChainId=137&\
dstToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&\
slippage=100&\
actionType=polymarket&\
userId=user_123&\
side=BUY&\
tokenID=80746058984644290629624903019922696017323803605256698757445938534814122585786&\
orderType=FAK&\
price=0.52&\
size=10&\
feeRateBps=0&\
tickSize=0.01&\
negRisk=false&\
recipient=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd&\
swapDirection=exact-amount-in" \
  -H "x-api-key: YOUR_API_KEY"

URL Encoding Notes

When constructing the URL manually, ensure proper URL encoding:

Spaces should be encoded as %20 or +
Special characters should be URL-encoded
The appFees parameter (if used) should be JSON-encoded: appFees=[{"bps":10,"flatFee":"0","receiverAddress":"0x..."}]

Parameter Validation

Side

Must be exactly "BUY" or "SELL" (case-sensitive)

OrderType

Must be exactly "FOK", "FAK", "GTC", or "GTD" (case-sensitive)

Price

Must be a number between 0 and 1 (exclusive of 0, inclusive of 1)
Required for limit orders (GTC/GTD)
Optional for market orders (FOK/FAK)

Size

Must be a positive number
Required for limit orders (GTC/GTD)
Optional for market orders (FOK/FAK)
The market details will contain a minimum size. Generally, the minimum size is 5.

Amount

Must be provided as a string representation of a bigint
For USDC on Polygon (6 decimals), 1 USDC = "1000000"
Required for market orders unless both price and size are provided

Slippage

Must be between 0 and 100 (for Polymarket orders)
Represented in basis points (100 = 1%)

FeeRateBps

The fee rate is currently 0 for Polymarket.
Must be a non-negative number
Represented in basis points

TickSize

Common values: "0.01", "0.001", "0.0001"
Can be any string value

NegRisk

Must be the string "true" or "false" (not boolean)

SwapDirection

Must be "exact-amount-in" or "exact-amount-out"
Defaults to "exact-amount-in" if not provided

Error Responses

The API may return the following error responses:

400 Bad Request: Missing required field or invalid parameter
401 Unauthorized: Invalid or missing API key
500 Internal Server Error: Server error

Error response format:

{
  "error": "Error message describing what went wrong"
}

Workflow Endpoints

All workflow endpoints are located under /api/workflows/polymarket/ and provide supporting functionality for Polymarket operations.

1. Create or Fetch Polymarket User

Creates a new Polymarket user or fetches an existing one based on the provided EVM address. Endpoint: POST /api/workflows/polymarket/createOrFetchPolymarketUser Request Body:

{
  "evmEoa": "0x1234567890123456789012345678901234567890"
}

Parameters:

Parameter	Type	Required	Description	Example
`evmEoa`	Address	Yes	EVM address (wallet address)	`0x1234...5678`

Response:

{
  "userCredentials": {
    "evmEoa": "0x1234567890123456789012345678901234567890",
    "proxyWallet": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "proxyWalletStatus": "ready"
  },
  "newUser": true,
  "userId": "user_123"
}

Response Object Types:

Field	Type	Required	Description	Example
`userCredentials`	object	Yes	User credentials object containing wallet information	See `UserCredentials` object below
`userCredentials.evmEoa`	Address	Yes	The “home” EOA address (wallet address)	`"0x1234567890123456789012345678901234567890"`
`userCredentials.proxyWallet`	Address	No	Proxy wallet address (if available)	`"0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"`
`userCredentials.proxyWalletStatus`	string	No	Status of the proxy wallet (maps to `ProxyWalletStatus` enum)	`"ready"`, `"deploying"`, `"permissioning"`, `"failed-deploy"`, `"failed-permission"`, `"not-created"`
`newUser`	boolean	Yes	Whether this is a newly created user (`true`) or existing user (`false`)	`true`
`userId`	string	Yes	Polymarket user ID	`"user_123"`

Proxy Wallet Status Values: The proxyWalletStatus field uses ProxyWalletStatus enum values:

"ready": Proxy wallet is ready to use
"deploying": Proxy wallet is being deployed
"permissioning": Proxy wallet permissions are being set up
"failed-deploy": Proxy wallet deployment failed
"failed-permission": Proxy wallet permission setup failed
"not-created": Proxy wallet has not been created

cURL Example:

curl -X POST "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/createOrFetchPolymarketUser" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "evmEoa": "0x1234567890123456789012345678901234567890"
  }'

Notes:

Use the returned userId in /api/getAction requests
Use the returned userCredentials.proxyWallet as the recipient address in /api/getAction requests (if available)
The newUser field indicates whether a new user was created or an existing user was fetched
Check proxyWalletStatus to determine if the proxy wallet is ready for use
This endpoint should be called before placing orders

2. Search Markets

Searches for Polymarket markets by query string. Endpoint: GET /api/workflows/polymarket/search Query Parameters:

Parameter	Type	Required	Description	Example
`q`	string	No	Search query string	`"american election"`
`tagIds`	number	No	Array of event tags ids (categories) to filter by. Retrieve ids from the `getTags` endpoint
`page`	number	No	Page number for pagination	`1`
`limit`	number	No	Limit results per type (tags, events, profiles)	`1`
`activeOnly`	boolean	No	Only return markets currently accepting orders	`true`

Response: The response is an array of events with their associated markets, along with pagination information.

View full response structure

{
  "events": [
    {
      "id": "903524",
      "ticker": "justin-fields-next-team",
      "slug": "justin-fields-next-team",
      "title": "Justin Fields Next Team",
      "description": "Event description...",
      "resolutionSource": "",
      "startDate": "2024-02-26T21:47:00Z",
      "creationDate": "2024-02-26T21:50:03.794Z",
      "endDate": "2024-04-25T00:00:00Z",
      "image": "https://...",
      "icon": "https://...",
      "active": true,
      "closed": true,
      "archived": false,
      "new": false,
      "featured": false,
      "restricted": true,
      "volume": 31264.48637,
      "openInterest": 0,
      "sortBy": "ascending",
      "published_at": "2024-02-22 17:23:50.05+00",
      "createdAt": "2024-02-22T17:23:50.074Z",
      "updatedAt": "2024-05-07T23:10:20.120507Z",
      "commentsEnabled": false,
      "competitive": 1,
      "volume1wk": 0,
      "volume1mo": 0,
      "volume1yr": 0,
      "featuredImage": "",
      "enableOrderBook": true,
      "negRisk": true,
      "negRiskMarketID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
      "negRiskFeeBips": 0,
      "commentCount": 0,
      "markets": [
        {
          "id": "254632",
          "question": "Will Justin Fields be traded to the Atlanta Falcons?",
          "conditionId": "0x34b24f445ed6321fe7c91c163b512239dcf122d39881b82850e3a0ca09ac665a",
          "slug": "will-justin-fields-be-traded-to-the-atlanta-falcons",
          "resolutionSource": "",
          "endDate": "2024-04-25T00:00:00Z",
          "liquidity": "231.2",
          "startDate": "2024-02-26T21:47:00Z",
          "fee": "20000000000000000",
          "image": "https://...",
          "icon": "https://...",
          "description": "Market description...",
          "outcomes": "[\"Yes\", \"No\"]",
          "outcomePrices": "[\"0\", \"1\"]",
          "volume": "4101.429276",
          "active": true,
          "marketType": "normal",
          "closed": true,
          "marketMakerAddress": "",
          "createdAt": "2024-02-22T17:23:49.934Z",
          "updatedAt": "2024-04-26T02:52:34.331768Z",
          "closedTime": "2024-03-21 01:19:19+00",
          "wideFormat": false,
          "new": false,
          "featured": false,
          "submitted_by": "0x91430CaD2d3975766499717fA0D66A78D814E5c5",
          "archived": false,
          "resolvedBy": "0x2F5e3684cb1F318ec51b00Edba38d79Ac2c0aA9d",
          "restricted": true,
          "groupItemTitle": "Falcons",
          "groupItemThreshold": "1",
          "questionID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
          "umaEndDate": "2024-03-21 01:19:19+00",
          "enableOrderBook": true,
          "orderPriceMinTickSize": 0.001,
          "orderMinSize": 5,
          "umaResolutionStatus": "resolved",
          "volumeNum": 4101.43,
          "liquidityNum": 231.2,
          "endDateIso": "2024-04-25",
          "hasReviewedDates": true,
          "commentsEnabled": false,
          "volume24hr": 0,
          "volume1wk": 0,
          "volume1mo": 0,
          "volume1yr": 0,
          "secondsDelay": 0,
          "clobTokenIds": "[\"60514145194897823219826772428422448353518550507265497262875791233246155902231\", \"79441287910732946721658295867280356011681250132429753298939411798136774417659\"]",
          "umaBond": "500.0",
          "umaReward": "5.0",
          "fpmmLive": true,
          "volume24hrAmm": 0,
          "volume1wkAmm": 0,
          "volume1moAmm": 0,
          "volume1yrAmm": 0,
          "volume24hrClob": 0,
          "volume1wkClob": 0,
          "volume1moClob": 0,
          "volume1yrClob": 0,
          "volumeAmm": 0,
          "volumeClob": 4101.429276,
          "liquidityAmm": 0,
          "liquidityClob": 0,
          "makerBaseFee": 0,
          "takerBaseFee": 0,
          "customLiveness": 0,
          "acceptingOrders": true,
          "negRisk": true,
          "negRiskMarketID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
          "negRiskRequestID": "0x93cd45e01d1085855eda9d2a3709683c3a3a479fdbc6e49a056df132228c6ce1",
          "notificationsEnabled": true,
          "creator": "",
          "ready": false,
          "funded": false,
          "cyom": false,
          "competitive": 0,
          "pagerDutyNotificationEnabled": false,
          "approved": true,
          "rewardsMinSize": 0,
          "rewardsMaxSpread": 0,
          "spread": 1,
          "oneDayPriceChange": 0,
          "oneHourPriceChange": 0,
          "oneWeekPriceChange": 0,
          "oneMonthPriceChange": 0,
          "oneYearPriceChange": 0,
          "lastTradePrice": 0,
          "bestBid": 0,
          "bestAsk": 1,
          "clearBookOnStart": true,
          "manualActivation": false,
          "negRiskOther": false,
          "umaResolutionStatuses": "[]",
          "pendingDeployment": false,
          "deploying": false,
          "rfqEnabled": false,
          "holdingRewardsEnabled": false,
          "feesEnabled": false
        }
      ],
      "cyom": false,
      "closedTime": "2024-03-21T01:24:40.970783Z",
      "showAllOutcomes": false,
      "showMarketImages": true,
      "enableNegRisk": true,
      "negRiskAugmented": false,
      "pendingDeployment": false,
      "deploying": false
    }
  ],
  "pagination": {
    "hasMore": false,
    "totalResults": 2
  }
}

Response Fields:

Field	Type	Description
`events`	array	Array of event objects, each containing markets and tags
`pagination`	object	Pagination information
`pagination.hasMore`	boolean	Whether there are more results available
`pagination.totalResults`	number	Total number of results

cURL Examples: Search with query:

curl -G "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/search?q=patriots&activeOnly=true" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Search with tags:

curl -G "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/search?tagId=450&tagId=226" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

The q parameter should be URL-encoded
Event tags are categories used to filter Polymarket markets (e.g., “nfl”, “sports”, “politics”)
Multiple event tags will search on events with all tags vs. returning events that match any tag
Only markets with acceptingOrders: true can be used for orders
The clobTokenIds field contains a JSON array of token IDs (use index 0 for “Yes”, index 1 for “No”)
The response includes pagination information in the pagination object

3. Get Markets

Retrieves market information by CLOB token IDs or slugs. Endpoint: GET /api/workflows/polymarket/getMarkets Query Parameters:

Parameter	Type	Required	Description	Example
`clobTokenIds`	string[]	No	Array of CLOB token IDs (can be comma-separated or JSON array)	`"tokenId1,tokenId2"` or `["tokenId1","tokenId2"]`
`slug`	string	No	Array of market slugs (can be comma-separated or JSON array)	`"slug1,slug2"` or `["slug1","slug2"]`
`tagId`	number	No	Tag Id from the `getTags` endpoint	`450`

*At least one of clobTokenIds or slugs must be provided. Response: The response follows the standardized response format with events, tags, and pagination information.

View full response structure

{
  "events": [
    {
      "id": "903524",
      "ticker": "justin-fields-next-team",
      "slug": "justin-fields-next-team",
      "title": "Justin Fields Next Team",
      "description": "Event description...",
      "resolutionSource": "",
      "startDate": "2024-02-26T21:47:00Z",
      "creationDate": "2024-02-26T21:50:03.794Z",
      "endDate": "2024-04-25T00:00:00Z",
      "image": "https://...",
      "icon": "https://...",
      "active": true,
      "closed": true,
      "archived": false,
      "new": false,
      "featured": false,
      "restricted": true,
      "volume": 31264.48637,
      "openInterest": 0,
      "sortBy": "ascending",
      "published_at": "2024-02-22 17:23:50.05+00",
      "createdAt": "2024-02-22T17:23:50.074Z",
      "updatedAt": "2024-05-07T23:10:20.120507Z",
      "commentsEnabled": false,
      "competitive": 1,
      "volume1wk": 0,
      "volume1mo": 0,
      "volume1yr": 0,
      "featuredImage": "",
      "enableOrderBook": true,
      "negRisk": true,
      "negRiskMarketID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
      "negRiskFeeBips": 0,
      "commentCount": 0,
      "markets": [
        {
          "id": "254632",
          "question": "Will Justin Fields be traded to the Atlanta Falcons?",
          "conditionId": "0x34b24f445ed6321fe7c91c163b512239dcf122d39881b82850e3a0ca09ac665a",
          "slug": "will-justin-fields-be-traded-to-the-atlanta-falcons",
          "resolutionSource": "",
          "endDate": "2024-04-25T00:00:00Z",
          "liquidity": "231.2",
          "startDate": "2024-02-26T21:47:00Z",
          "fee": "20000000000000000",
          "image": "https://...",
          "icon": "https://...",
          "description": "Market description...",
          "outcomes": "[\"Yes\", \"No\"]",
          "outcomePrices": "[\"0\", \"1\"]",
          "volume": "4101.429276",
          "active": true,
          "marketType": "normal",
          "closed": true,
          "marketMakerAddress": "",
          "createdAt": "2024-02-22T17:23:49.934Z",
          "updatedAt": "2024-04-26T02:52:34.331768Z",
          "closedTime": "2024-03-21 01:19:19+00",
          "wideFormat": false,
          "new": false,
          "featured": false,
          "submitted_by": "0x91430CaD2d3975766499717fA0D66A78D814E5c5",
          "archived": false,
          "resolvedBy": "0x2F5e3684cb1F318ec51b00Edba38d79Ac2c0aA9d",
          "restricted": true,
          "groupItemTitle": "Falcons",
          "groupItemThreshold": "1",
          "questionID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
          "umaEndDate": "2024-03-21 01:19:19+00",
          "enableOrderBook": true,
          "orderPriceMinTickSize": 0.001,
          "orderMinSize": 5,
          "umaResolutionStatus": "resolved",
          "volumeNum": 4101.43,
          "liquidityNum": 231.2,
          "endDateIso": "2024-04-25",
          "hasReviewedDates": true,
          "commentsEnabled": false,
          "volume24hr": 0,
          "volume1wk": 0,
          "volume1mo": 0,
          "volume1yr": 0,
          "secondsDelay": 0,
          "clobTokenIds": "[\"60514145194897823219826772428422448353518550507265497262875791233246155902231\", \"79441287910732946721658295867280356011681250132429753298939411798136774417659\"]",
          "umaBond": "500.0",
          "umaReward": "5.0",
          "fpmmLive": true,
          "volume24hrAmm": 0,
          "volume1wkAmm": 0,
          "volume1moAmm": 0,
          "volume1yrAmm": 0,
          "volume24hrClob": 0,
          "volume1wkClob": 0,
          "volume1moClob": 0,
          "volume1yrClob": 0,
          "volumeAmm": 0,
          "volumeClob": 4101.429276,
          "liquidityAmm": 0,
          "liquidityClob": 0,
          "makerBaseFee": 0,
          "takerBaseFee": 0,
          "customLiveness": 0,
          "acceptingOrders": true,
          "negRisk": true,
          "negRiskMarketID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
          "negRiskRequestID": "0x93cd45e01d1085855eda9d2a3709683c3a3a479fdbc6e49a056df132228c6ce1",
          "notificationsEnabled": true,
          "creator": "",
          "ready": false,
          "funded": false,
          "cyom": false,
          "competitive": 0,
          "pagerDutyNotificationEnabled": false,
          "approved": true,
          "rewardsMinSize": 0,
          "rewardsMaxSpread": 0,
          "spread": 1,
          "oneDayPriceChange": 0,
          "oneHourPriceChange": 0,
          "oneWeekPriceChange": 0,
          "oneMonthPriceChange": 0,
          "oneYearPriceChange": 0,
          "lastTradePrice": 0,
          "bestBid": 0,
          "bestAsk": 1,
          "clearBookOnStart": true,
          "manualActivation": false,
          "negRiskOther": false,
          "umaResolutionStatuses": "[]",
          "pendingDeployment": false,
          "deploying": false,
          "rfqEnabled": false,
          "holdingRewardsEnabled": false,
          "feesEnabled": false
        }
      ],
      "cyom": false,
      "closedTime": "2024-03-21T01:24:40.970783Z",
      "showAllOutcomes": false,
      "showMarketImages": true,
      "enableNegRisk": true,
      "negRiskAugmented": false,
      "pendingDeployment": false,
      "deploying": false
    }
  ],
  "pagination": {
    "hasMore": false,
    "totalResults": 1
  }
}

Response Fields:

Field	Type	Description
`events`	array	Array of event objects, each containing markets and tags
`pagination`	object	Pagination information
`pagination.hasMore`	boolean	Whether there are more results available
`pagination.totalResults`	number	Total number of results

**cURL Examples:**

With comma-separated token IDs:

```bash
curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getMarkets?clobTokenIds=tokenId1,tokenId2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

With multiple token IDs as separate parameters:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getMarkets?clobTokenIds=tokenId1&clobTokenIds=tokenId2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

With slugs:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getMarkets?slugs=slug1,slug2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Token IDs can be provided as comma-separated strings or as a JSON array
Multiple parameters can be passed by repeating the query parameter or using comma separation
The response follows the standardized response format with events and pagination fields
Only markets with acceptingOrders: true can be used for orders
The clobTokenIds field contains a JSON array of token IDs (use index 0 for “Yes”, index 1 for “No”)

4. Get Price

Retrieves the current market price for a specific token and side. Endpoint: GET /api/workflows/polymarket/getPrice Query Parameters:

Parameter	Type	Required	Description	Example
`clobTokenId`	string	Yes	CLOB token ID	`"80746058984644290629624903019922696017323803605256698757445938534814122585786"`
`side`	string	Yes	Order side: `"BUY"` or `"SELL"` (case-insensitive)	`"BUY"`

Response:

{
  "price": 0.52
}

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getPrice?clobTokenId=80746058984644290629624903019922696017323803605256698757445938534814122585786&side=BUY" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

The side parameter is case-insensitive (will be converted to uppercase)
Returns the best available price for the specified side

Retrieves trending markets on Polymarket. Endpoint: GET /api/workflows/polymarket/getTrendingMarkets Query Parameters:

Parameter	Type	Required	Description	Example
`limit`	number	No	Maximum number of results to return	`20`
`page`	number	No	Page number for pagination	`2`

Response: The response follows the standardized response format with events, tags, and pagination information.

View full response structure

{
  "events": [
    {
      "id": "903524",
      "ticker": "justin-fields-next-team",
      "slug": "justin-fields-next-team",
      "title": "Justin Fields Next Team",
      "description": "Event description...",
      "resolutionSource": "",
      "startDate": "2024-02-26T21:47:00Z",
      "creationDate": "2024-02-26T21:50:03.794Z",
      "endDate": "2024-04-25T00:00:00Z",
      "image": "https://...",
      "icon": "https://...",
      "active": true,
      "closed": true,
      "archived": false,
      "new": false,
      "featured": false,
      "restricted": true,
      "volume": 31264.48637,
      "openInterest": 0,
      "sortBy": "ascending",
      "published_at": "2024-02-22 17:23:50.05+00",
      "createdAt": "2024-02-22T17:23:50.074Z",
      "updatedAt": "2024-05-07T23:10:20.120507Z",
      "commentsEnabled": false,
      "competitive": 1,
      "volume1wk": 0,
      "volume1mo": 0,
      "volume1yr": 0,
      "featuredImage": "",
      "enableOrderBook": true,
      "negRisk": true,
      "negRiskMarketID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
      "negRiskFeeBips": 0,
      "commentCount": 0,
      "markets": [
        {
          "id": "254632",
          "question": "Will Justin Fields be traded to the Atlanta Falcons?",
          "conditionId": "0x34b24f445ed6321fe7c91c163b512239dcf122d39881b82850e3a0ca09ac665a",
          "slug": "will-justin-fields-be-traded-to-the-atlanta-falcons",
          "resolutionSource": "",
          "endDate": "2024-04-25T00:00:00Z",
          "liquidity": "231.2",
          "startDate": "2024-02-26T21:47:00Z",
          "fee": "20000000000000000",
          "image": "https://...",
          "icon": "https://...",
          "description": "Market description...",
          "outcomes": "[\"Yes\", \"No\"]",
          "outcomePrices": "[\"0\", \"1\"]",
          "volume": "4101.429276",
          "active": true,
          "marketType": "normal",
          "closed": true,
          "marketMakerAddress": "",
          "createdAt": "2024-02-22T17:23:49.934Z",
          "updatedAt": "2024-04-26T02:52:34.331768Z",
          "closedTime": "2024-03-21 01:19:19+00",
          "wideFormat": false,
          "new": false,
          "featured": false,
          "submitted_by": "0x91430CaD2d3975766499717fA0D66A78D814E5c5",
          "archived": false,
          "resolvedBy": "0x2F5e3684cb1F318ec51b00Edba38d79Ac2c0aA9d",
          "restricted": true,
          "groupItemTitle": "Falcons",
          "groupItemThreshold": "1",
          "questionID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
          "umaEndDate": "2024-03-21 01:19:19+00",
          "enableOrderBook": true,
          "orderPriceMinTickSize": 0.001,
          "orderMinSize": 5,
          "umaResolutionStatus": "resolved",
          "volumeNum": 4101.43,
          "liquidityNum": 231.2,
          "endDateIso": "2024-04-25",
          "hasReviewedDates": true,
          "commentsEnabled": false,
          "volume24hr": 0,
          "volume1wk": 0,
          "volume1mo": 0,
          "volume1yr": 0,
          "secondsDelay": 0,
          "clobTokenIds": "[\"60514145194897823219826772428422448353518550507265497262875791233246155902231\", \"79441287910732946721658295867280356011681250132429753298939411798136774417659\"]",
          "umaBond": "500.0",
          "umaReward": "5.0",
          "fpmmLive": true,
          "volume24hrAmm": 0,
          "volume1wkAmm": 0,
          "volume1moAmm": 0,
          "volume1yrAmm": 0,
          "volume24hrClob": 0,
          "volume1wkClob": 0,
          "volume1moClob": 0,
          "volume1yrClob": 0,
          "volumeAmm": 0,
          "volumeClob": 4101.429276,
          "liquidityAmm": 0,
          "liquidityClob": 0,
          "makerBaseFee": 0,
          "takerBaseFee": 0,
          "customLiveness": 0,
          "acceptingOrders": true,
          "negRisk": true,
          "negRiskMarketID": "0xcd0126143cb6daf16e3d8410ee82c0b963e250c8a4922850e1135e7926fd1000",
          "negRiskRequestID": "0x93cd45e01d1085855eda9d2a3709683c3a3a479fdbc6e49a056df132228c6ce1",
          "notificationsEnabled": true,
          "creator": "",
          "ready": false,
          "funded": false,
          "cyom": false,
          "competitive": 0,
          "pagerDutyNotificationEnabled": false,
          "approved": true,
          "rewardsMinSize": 0,
          "rewardsMaxSpread": 0,
          "spread": 1,
          "oneDayPriceChange": 0,
          "oneHourPriceChange": 0,
          "oneWeekPriceChange": 0,
          "oneMonthPriceChange": 0,
          "oneYearPriceChange": 0,
          "lastTradePrice": 0,
          "bestBid": 0,
          "bestAsk": 1,
          "clearBookOnStart": true,
          "manualActivation": false,
          "negRiskOther": false,
          "umaResolutionStatuses": "[]",
          "pendingDeployment": false,
          "deploying": false,
          "rfqEnabled": false,
          "holdingRewardsEnabled": false,
          "feesEnabled": false
        }
      ],
      "tags": [
        {
          "id": "1449",
          "label": "las vegas raiders",
          "slug": "las-vegas-raiders",
          "publishedAt": "2024-02-26 21:43:16.042+00",
          "createdAt": "2024-02-26T21:43:16.586Z",
          "updatedAt": "2024-02-26T21:43:16.586Z"
        }
      ],
      "cyom": false,
      "closedTime": "2024-03-21T01:24:40.970783Z",
      "showAllOutcomes": false,
      "showMarketImages": true,
      "enableNegRisk": true,
      "negRiskAugmented": false,
      "pendingDeployment": false,
      "deploying": false
    }
  ],
  "pagination": {
    "hasMore": false,
    "totalResults": 2
  }
}

Response Fields:

Field	Type	Description
`events`	array	Array of event objects, each containing markets and tags
`pagination`	object	Pagination information
`pagination.hasMore`	boolean	Whether there are more results available
`pagination.totalResults`	number	Total number of results

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getTrendingMarkets?limit=20" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Returns active markets sorted by 24hr volume. Markets must have minimum $150K of volume
The limit parameter controls how many trending markets are returned
The response follows the standardized response format with events and pagination fields
Only markets with acceptingOrders: true can be used for orders
The clobTokenIds field contains a JSON array of token IDs (use index 0 for “Yes”, index 1 for “No”)

6. Get Trades

Retrieves trade history for a specific user. Endpoint: GET /api/workflows/polymarket/getTrades Query Parameters:

Parameter	Type	Required	Description	Example
`userId`	string	Yes	User EVM EOA Address	`0x123..789`
`proxyWallet`	string	No	Polymarket proxy wallet address	`0x456..789`
`limit`	number	No	Maximum number of results to return	`50`
`offset`	number	No	Number of results to skip (for pagination)	`0`

Response:

{
  "trades": [
    {
      "id": "trade_id_123",
      "marketId": "market_id_123",
      "side": "BUY",
      "price": 0.52,
      "size": 10,
      "timestamp": 1735689600
    }
  ],
  "total": 100
}

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getTrades?userId=user_123&limit=50&offset=0" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Results are paginated using limit and offset
Use offset to fetch subsequent pages

7. Get Activity

Retrieves activity history for a specific user. Endpoint: GET /api/workflows/polymarket/getActivity Query Parameters:

Parameter	Type	Required	Description	Example
`userId`	string	Yes	User EVM EOA Address	`0x123..789`
`proxyWallet`	string	No	Polymarket proxy wallet address	`0x456..789`
`limit`	number	No	Maximum number of results to return	`50`
`offset`	number	No	Number of results to skip (for pagination)	`0`

Response:

{
  "activities": [
    {
      "id": "activity_id_123",
      "type": "order_placed",
      "marketId": "market_id_123",
      "timestamp": 1735689600,
      "details": {}
    }
  ],
  "total": 100
}

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getActivity?userId=user_123&limit=50&offset=0" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Returns a comprehensive activity feed including orders, trades, and other actions
Results are paginated using limit and offset

8. Get Current Positions

Retrieves current open positions for a specific user. Endpoint: GET /api/workflows/polymarket/getCurrentPositions Query Parameters:

Parameter	Type	Required	Description	Example
`userId`	string	Yes	User EVM EOA Address	`0x123..789`
`proxyWallet`	string	No	Polymarket proxy wallet address	`0x456..789`
`redeemable`	boolean	No	Filter for redeemable positions only	`true`
`mergable`	boolean	No	Filter for mergable positions only	`true`
`limit`	number	No	Maximum number of results to return	`50`
`offset`	number	No	Number of results to skip (for pagination)	`0`

Response:

{
  "positions": [
    {
      "id": "position_id_123",
      "marketId": "market_id_123",
      "outcome": "Yes",
      "shares": 10,
      "averagePrice": 0.52,
      "currentPrice": 0.55,
      "redeemable": false,
      "mergable": false
    }
  ],
  "total": 25
}

cURL Examples: Get all current positions:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getCurrentPositions?userId=user_123&limit=50&offset=0" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Get only redeemable positions:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getCurrentPositions?userId=user_123&redeemable=true" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Get only mergable positions:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getCurrentPositions?userId=user_123&mergable=true" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

redeemable and mergable are boolean query parameters (use true or false as strings)
Results are paginated using limit and offset

9. Get Closed Positions

Retrieves closed positions (resolved markets) for a specific user. Endpoint: GET /api/workflows/polymarket/getClosedPositions Query Parameters:

Parameter	Type	Required	Description	Example
`userId`	string	Yes	User EVM EOA Address	`0x123..789`
`proxyWallet`	string	No	Polymarket proxy wallet address	`0x456..789`
`limit`	number	No	Maximum number of results to return	`50`
`offset`	number	No	Number of results to skip (for pagination)	`0`

Response:

{
  "positions": [
    {
      "id": "position_id_123",
      "marketId": "market_id_123",
      "outcome": "Yes",
      "shares": 10,
      "averagePrice": 0.52,
      "finalPrice": 1.0,
      "resolvedAt": 1735689600
    }
  ],
  "total": 15
}

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getClosedPositions?userId=user_123&limit=50&offset=0" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Returns positions from markets that have been resolved
Results are paginated using limit and offset

10. Get PnL

Retrieves profit and loss information for a specific user. Endpoint: GET /api/workflows/polymarket/getPnL Query Parameters:

Parameter	Type	Required	Description	Example
`userId`	string	Yes	User EVM EOA Address	`0x123..789`
`proxyWallet`	string	No	Polymarket proxy wallet address	`0x456..789`

Response:

{
  "totalPnL": 1250.5,
  "realizedPnL": 500.25,
  "unrealizedPnL": 750.25,
  "currency": "USDC"
}

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/getPnL?userId=user_123" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Returns aggregate PnL across all positions
realizedPnL includes profits/losses from closed positions
unrealizedPnL includes profits/losses from open positions based on current prices

11. Cancel Order

Cancels one or more open orders. Endpoint: POST /api/workflows/polymarket/cancelOrder Request Body:

{
  "evmEoa": "0x1234567890123456789012345678901234567890",
  "proxyWallet": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
  "orderIDs": ["order_id_1", "order_id_2"]
}

Parameters:

Parameter	Type	Required	Description	Example
`evmEoa`	Address	Yes	EVM address (wallet address)	`0x1234...5678`
`proxyWallet`	Address	No	Proxy wallet address (if different from evmEoa)	`0xabcd...efgh`
`orderIDs`	string[]	Yes	Array of order IDs to cancel	`["order_id_1", "order_id_2"]`

Response:

{
  "success": true,
  "cancelledOrders": ["order_id_1", "order_id_2"],
  "message": "Orders cancelled successfully"
}

cURL Example:

curl -X POST "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/polymarket/cancelOrder" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "evmEoa": "0x1234567890123456789012345678901234567890",
    "proxyWallet": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "orderIDs": ["order_id_1", "order_id_2"]
  }'

Notes:

orderIDs must be a non-empty array
proxyWallet is optional but recommended if you have a proxy wallet associated with the user
Only open orders can be cancelled

12. Get Workflow Status

Retrieves the status of a workflow transaction. Endpoint: GET /api/workflows/getStatus Query Parameters:

Parameter	Type	Required	Description	Example
`txId`	string	Yes	Transaction ID from /getAction request	`"0x30e7dc0566713417a7bc136ad3bb4f8525e005e2e024ef696b7b88f497e394e8"`

Response:

View full response structure

{
  "txId": "0x30e7dc0566713417a7bc136ad3bb4f8525e005e2e024ef696b7b88f497e394e8",
  "workflow": {
    "data": {
      "userId": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892",
      "orderRequest": {
        "side": "BUY",
        "tokenID": "110902308091723190012269532299497167125504426554890434343419495764557291673806",
        "orderType": "GTD",
        "feeRateBps": 0,
        "slippage": 100,
        "tickSize": "0.01",
        "negRisk": false,
        "price": 0.021,
        "size": 5,
        "expiration": 10
      },
      "orderResponse": {
        "id": "0xbd2f3c625c1f6f918a74e8645c3afee9e8f2c5adf91f178efa5e1b65f74fb489",
        "status": "MATCHED",
        "owner": "258f7485-b93f-52e5-2327-a53c49a299c1",
        "maker_address": "0xBEDcAD563ddf52391573a016Bc5EC7A334Eec756",
        "market": "0xb050c89e1e5738c79e117d28da1f057ac2f193511aab87a01b517b466c7265dc",
        "asset_id": "110902308091723190012269532299497167125504426554890434343419495764557291673806",
        "side": "BUY",
        "original_size": "5",
        "size_matched": "0",
        "price": "0.02",
        "outcome": "No",
        "expiration": "1763996360",
        "order_type": "GTD",
        "associate_trades": [],
        "created_at": 1763996291
      }
    },
    "name": "polymarket",
    "operation": "placeOrder",
    "status": "success",
    "timestamp": 1763996274
  }
}

Response Fields:

Field	Type	Description
`txId`	string	Transaction ID from workflow
`workflow`	object	Workflow information object
`workflow.data`	object	Workflow data containing order request and response
`workflow.data.userId`	string	User ID from create or fetch user response
`workflow.data.orderRequest`	object	Original order request parameters
`workflow.data.orderResponse`	object	Order response from Polymarket (if order was placed)
`workflow.name`	string	Workflow name (e.g., `"polymarket"`)
`workflow.operation`	string	Operation type (e.g., `"placeOrder"`)
`workflow.status`	string	Workflow status: `"pending"`, `"success"`, or `"failed"`
`workflow.timestamp`	number	Timestamp of the workflow operation

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/getStatus?txId=0x30e7dc0566713417a7bc136ad3bb4f8525e005e2e024ef696b7b88f497e394e8" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Notes:

Use this endpoint to check the status of a workflow transaction after submission
The txId is typically returned from the /api/getAction endpoint
Status values: pending, success, failed

13. Get Tags

Retrieves the status of a workflow transaction. Endpoint: GET /api/workflows/getTags Query Parameters:

Parameter	Type	Required	Description	Example
`limit`	number	No	Number of tags to return	`5`
`offset`	number	No	Zero-based index of first index to return	`5`
`slug`	string	No	Transaction ID from /getAction request	`"nfl"`

Response:

View full response structure

[
  {
    "id": "207",
    "label": "dating",
    "slug": "dating",
    "publishedAt": "2023-11-02 21:35:57.945+00",
    "createdAt": "2023-11-02T21:35:57.968Z",
    "updatedAt": "2023-11-02T21:35:57.968Z"
  }
]

Response Fields:

Field	Type	Description
`id`	string	Tag ID. Can search markets based on tag ID.
`label`	string	Label for tag
`slug`	string	Slug for tag. Can search tags based on slug.
`publishedAt`	string	Tag publish date
`createdAt`	string	Tag creation date
`updatedAt`	string	Tag updated date

cURL Example:

curl -X GET "https://box-api-git-tw-staging-decent-webapp.vercel.app/api/workflows/getTags" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

General Notes

Chain Support: Polymarket operates on Polygon. The destination chain should always be Polygon (137).
Token: Polymarket settles trades in USDC.e on Polygon. The destination token should always be the USDC.e address: 0x2791bca1f2de4661ed88a30c99a7a9449aa84174
Amount Format: Amounts are provided as string representations of bigint values. For USDC (6 decimals), multiply the USD amount by 1,000,000
Order Types:
- FOK (Fill or Kill): Order must fill completely or be cancelled
- FAK (Fill and Kill): Order fills as much as possible, then cancels remainder
- GTC (Good til Cancelled): Limit order that remains active until filled or cancelled
- GTD (Good til Date): Limit order that expires at a specific time
Response Parsing: The response contains bigint values that need to be deserialized. Use a bigint deserializer when parsing JSON responses.
Error Handling: All endpoints may return standard HTTP error codes (400, 401, 500) with error messages in JSON format
Pagination: Endpoints that support pagination use limit and offset query parameters
URL Encoding: When constructing URLs manually, ensure proper URL encoding for query parameters

Getting started

Guides

Resources

​API Specification: Polymarket Endpoints

​Overview

​Table of Contents

​Authentication

​Base URL

​Main Endpoint: /api/getAction

​Overview

​Endpoint

​Request Parameters

​Base Action Request Parameters (Required)

​Polymarket-Specific Parameters (Required)

​Order Type-Specific Parameters

​Limit Orders (GTC/GTD) - Required Fields

​Market Orders (FOK/FAK) - Optional Fields

​Response

​Example cURL Requests

​Example 1: Market Order (FOK) - Buy

​Example 2: Limit Order (GTC) - Sell with Price and Size

​Example 3: Limit Order (GTD) - Buy with Expiration

​Example 4: Market Order (FAK) - Buy with Price and Size (amount calculated)

​URL Encoding Notes

​Parameter Validation

​Side

​OrderType

​Price

​Size

​Amount

​Slippage

​FeeRateBps

​TickSize

​NegRisk

​SwapDirection

​Error Responses

​Workflow Endpoints

​1. Create or Fetch Polymarket User

​2. Search Markets

​3. Get Markets

​4. Get Price

​5. Get Trending Markets

​6. Get Trades

​7. Get Activity

​8. Get Current Positions

​9. Get Closed Positions

​10. Get PnL

​11. Cancel Order

​12. Get Workflow Status

​13. Get Tags

​General Notes

API Specification: Polymarket Endpoints

Overview

Table of Contents

Authentication

Base URL

Main Endpoint: `/api/getAction`

Overview

Endpoint

Request Parameters

Base Action Request Parameters (Required)

Polymarket-Specific Parameters (Required)

Order Type-Specific Parameters

Limit Orders (GTC/GTD) - Required Fields

Market Orders (FOK/FAK) - Optional Fields

Response

Example cURL Requests

Example 1: Market Order (FOK) - Buy

Example 2: Limit Order (GTC) - Sell with Price and Size

Example 3: Limit Order (GTD) - Buy with Expiration

Example 4: Market Order (FAK) - Buy with Price and Size (amount calculated)

URL Encoding Notes

Parameter Validation

Side

OrderType

Price

Size

Amount

Slippage

FeeRateBps

TickSize

NegRisk

SwapDirection

Error Responses

Workflow Endpoints

1. Create or Fetch Polymarket User

2. Search Markets

3. Get Markets

4. Get Price

5. Get Trending Markets

6. Get Trades

7. Get Activity

8. Get Current Positions

9. Get Closed Positions

10. Get PnL

11. Cancel Order

12. Get Workflow Status

13. Get Tags

General Notes