Get Position Share Card Snapshots

curl --request POST \
  --url https://api.perpetuals.polymarket.com/v1/info/position-snapshots \
  --header 'Content-Type: application/json' \
  --header 'POLYMARKET-PROXY: <api-key>' \
  --header 'POLYMARKET-SECRET: <api-key>' \
  --data '
{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "active_instrument_ids": [
    2147483647
  ],
  "history_fills": [
    {
      "instrument_id": 2147483647,
      "trade_id": "<string>",
      "timestamp": 9223372036854
    }
  ]
}
'

import requests

url = "https://api.perpetuals.polymarket.com/v1/info/position-snapshots"

payload = {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "active_instrument_ids": [2147483647],
    "history_fills": [
        {
            "instrument_id": 2147483647,
            "trade_id": "<string>",
            "timestamp": 9223372036854
        }
    ]
}
headers = {
    "POLYMARKET-PROXY": "<api-key>",
    "POLYMARKET-SECRET": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'POLYMARKET-PROXY': '<api-key>',
    'POLYMARKET-SECRET': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address: '0x1234567890abcdef1234567890abcdef12345678',
    active_instrument_ids: [2147483647],
    history_fills: [{instrument_id: 2147483647, trade_id: '<string>', timestamp: 9223372036854}]
  })
};

fetch('https://api.perpetuals.polymarket.com/v1/info/position-snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.perpetuals.polymarket.com/v1/info/position-snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'address' => '0x1234567890abcdef1234567890abcdef12345678',
    'active_instrument_ids' => [
        2147483647
    ],
    'history_fills' => [
        [
                'instrument_id' => 2147483647,
                'trade_id' => '<string>',
                'timestamp' => 9223372036854
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "POLYMARKET-PROXY: <api-key>",
    "POLYMARKET-SECRET: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.perpetuals.polymarket.com/v1/info/position-snapshots"

	payload := strings.NewReader("{\n  \"address\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"active_instrument_ids\": [\n    2147483647\n  ],\n  \"history_fills\": [\n    {\n      \"instrument_id\": 2147483647,\n      \"trade_id\": \"<string>\",\n      \"timestamp\": 9223372036854\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("POLYMARKET-PROXY", "<api-key>")
	req.Header.Add("POLYMARKET-SECRET", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.perpetuals.polymarket.com/v1/info/position-snapshots")
  .header("POLYMARKET-PROXY", "<api-key>")
  .header("POLYMARKET-SECRET", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"address\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"active_instrument_ids\": [\n    2147483647\n  ],\n  \"history_fills\": [\n    {\n      \"instrument_id\": 2147483647,\n      \"trade_id\": \"<string>\",\n      \"timestamp\": 9223372036854\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.perpetuals.polymarket.com/v1/info/position-snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["POLYMARKET-PROXY"] = '<api-key>'
request["POLYMARKET-SECRET"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"active_instrument_ids\": [\n    2147483647\n  ],\n  \"history_fills\": [\n    {\n      \"instrument_id\": 2147483647,\n      \"trade_id\": \"<string>\",\n      \"timestamp\": 9223372036854\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "history_as_of_at": 1,
  "active": [
    {
      "status": "ok",
      "instrument_id": 1,
      "trade_id": "<string>",
      "snapshot": {
        "position_cycle_id": "<string>",
        "side": "long",
        "started_at": 1,
        "as_of_at": 1,
        "is_closed": true,
        "size_after": "<string>",
        "entry_price": "<string>",
        "as_of_price": "<string>",
        "pnl": "<string>",
        "pnl_percent": "<string>",
        "leverage": 1,
        "chart": {
          "candles": [
            {
              "position": 123,
              "open": 123,
              "high": 123,
              "low": 123,
              "close": 123
            }
          ],
          "markers": [
            {
              "position": 123,
              "kind": "increase"
            }
          ]
        }
      }
    }
  ],
  "history": [
    {
      "status": "ok",
      "instrument_id": 1,
      "trade_id": "<string>",
      "snapshot": {
        "position_cycle_id": "<string>",
        "side": "long",
        "started_at": 1,
        "as_of_at": 1,
        "is_closed": true,
        "size_after": "<string>",
        "entry_price": "<string>",
        "as_of_price": "<string>",
        "pnl": "<string>",
        "pnl_percent": "<string>",
        "leverage": 1,
        "chart": {
          "candles": [
            {
              "position": 123,
              "open": 123,
              "high": 123,
              "low": 123,
              "close": 123
            }
          ],
          "markers": [
            {
              "position": 123,
              "kind": "increase"
            }
          ]
        }
      }
    }
  ]
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

Get Position Share Card Snapshots

Build share-card numbers, candles and trade markers for a registered account. Supply up to 20 active instruments and 4 historical fills, with at least one selection. History keys use instrument_id, trade_id and the public fill timestamp in milliseconds. Trade IDs are UInt64 decimal strings; returned IDs omit leading zeroes. Duplicates and explicit null arrays are rejected. Weight is max(10, active + 7 × history).

Responses use Cache-Control: private, no-store. The route is public; valid owner authentication reveals leverage and pnl_percent. Both fields are null for anonymous callers and other accounts. Invalid supplied credentials return 401.

Active snapshots use captured state; history ends after the selected fill. A fill that closes a cycle, fully or by crossing, returns that closed cycle’s card. The cycle it opens is served by the active card or by its later fills. PositionCardSnapshot defines valuation, PnL and leverage availability.

Results preserve order within active and history. Only ok items contain snapshot. not_found means no current position or owned fill within history_as_of_at; gateways may have different horizons. history_pending means a known fill or a position needing bootstrap is ahead of completed history, or the self-match index coverage gate is not armed for historical cards; retry with backoff. history_limit means the reconstruction window lacks the opener. resource_limit means a row, memory or chart bound was exceeded. temporarily_unavailable includes deadlines and transient pricing or dependency failures. unavailable includes unsafe accounting, self-matches, backstop transfers, non-fill repairs and legacy multi-leg selections with unknowable fill order.

Candles include the selected minute’s aggregate, without a per-fill cutoff inside it. Charts retain the left boundary bucket and at least one hour of context, with at most 22 candles and 256 markers. Unknown accounts and malformed input return 400. Admission and shared dependency failures return 503; retry with backoff. HTTP 413 is reserved for an oversized request body.

POST

info

position-snapshots

Get Position Share Card Snapshots

curl --request POST \
  --url https://api.perpetuals.polymarket.com/v1/info/position-snapshots \
  --header 'Content-Type: application/json' \
  --header 'POLYMARKET-PROXY: <api-key>' \
  --header 'POLYMARKET-SECRET: <api-key>' \
  --data '
{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "active_instrument_ids": [
    2147483647
  ],
  "history_fills": [
    {
      "instrument_id": 2147483647,
      "trade_id": "<string>",
      "timestamp": 9223372036854
    }
  ]
}
'

import requests

url = "https://api.perpetuals.polymarket.com/v1/info/position-snapshots"

payload = {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "active_instrument_ids": [2147483647],
    "history_fills": [
        {
            "instrument_id": 2147483647,
            "trade_id": "<string>",
            "timestamp": 9223372036854
        }
    ]
}
headers = {
    "POLYMARKET-PROXY": "<api-key>",
    "POLYMARKET-SECRET": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'POLYMARKET-PROXY': '<api-key>',
    'POLYMARKET-SECRET': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address: '0x1234567890abcdef1234567890abcdef12345678',
    active_instrument_ids: [2147483647],
    history_fills: [{instrument_id: 2147483647, trade_id: '<string>', timestamp: 9223372036854}]
  })
};

fetch('https://api.perpetuals.polymarket.com/v1/info/position-snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.perpetuals.polymarket.com/v1/info/position-snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'address' => '0x1234567890abcdef1234567890abcdef12345678',
    'active_instrument_ids' => [
        2147483647
    ],
    'history_fills' => [
        [
                'instrument_id' => 2147483647,
                'trade_id' => '<string>',
                'timestamp' => 9223372036854
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "POLYMARKET-PROXY: <api-key>",
    "POLYMARKET-SECRET: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.perpetuals.polymarket.com/v1/info/position-snapshots"

	payload := strings.NewReader("{\n  \"address\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"active_instrument_ids\": [\n    2147483647\n  ],\n  \"history_fills\": [\n    {\n      \"instrument_id\": 2147483647,\n      \"trade_id\": \"<string>\",\n      \"timestamp\": 9223372036854\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("POLYMARKET-PROXY", "<api-key>")
	req.Header.Add("POLYMARKET-SECRET", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.perpetuals.polymarket.com/v1/info/position-snapshots")
  .header("POLYMARKET-PROXY", "<api-key>")
  .header("POLYMARKET-SECRET", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"address\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"active_instrument_ids\": [\n    2147483647\n  ],\n  \"history_fills\": [\n    {\n      \"instrument_id\": 2147483647,\n      \"trade_id\": \"<string>\",\n      \"timestamp\": 9223372036854\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.perpetuals.polymarket.com/v1/info/position-snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["POLYMARKET-PROXY"] = '<api-key>'
request["POLYMARKET-SECRET"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"active_instrument_ids\": [\n    2147483647\n  ],\n  \"history_fills\": [\n    {\n      \"instrument_id\": 2147483647,\n      \"trade_id\": \"<string>\",\n      \"timestamp\": 9223372036854\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "history_as_of_at": 1,
  "active": [
    {
      "status": "ok",
      "instrument_id": 1,
      "trade_id": "<string>",
      "snapshot": {
        "position_cycle_id": "<string>",
        "side": "long",
        "started_at": 1,
        "as_of_at": 1,
        "is_closed": true,
        "size_after": "<string>",
        "entry_price": "<string>",
        "as_of_price": "<string>",
        "pnl": "<string>",
        "pnl_percent": "<string>",
        "leverage": 1,
        "chart": {
          "candles": [
            {
              "position": 123,
              "open": 123,
              "high": 123,
              "low": 123,
              "close": 123
            }
          ],
          "markers": [
            {
              "position": 123,
              "kind": "increase"
            }
          ]
        }
      }
    }
  ],
  "history": [
    {
      "status": "ok",
      "instrument_id": 1,
      "trade_id": "<string>",
      "snapshot": {
        "position_cycle_id": "<string>",
        "side": "long",
        "started_at": 1,
        "as_of_at": 1,
        "is_closed": true,
        "size_after": "<string>",
        "entry_price": "<string>",
        "as_of_price": "<string>",
        "pnl": "<string>",
        "pnl_percent": "<string>",
        "leverage": 1,
        "chart": {
          "candles": [
            {
              "position": 123,
              "open": 123,
              "high": 123,
              "low": 123,
              "close": 123
            }
          ],
          "markers": [
            {
              "position": 123,
              "kind": "increase"
            }
          ]
        }
      }
    }
  ]
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

{
  "status": "err",
  "error": "insufficient_margin"
}

Request Weight: max(10, active + 7 × history)

Authorizations

POLYMARKET-PROXY

string

header

required

Proxy address

POLYMARKET-SECRET

string

header

required

Correponding proxy secret

Body

application/json

address

string

required

Address

Example:

"0x1234567890abcdef1234567890abcdef12345678"

active_instrument_ids

integer[]

Maximum array length: 20

Required range: 0 <= x <= 4294967295

history_fills

object[]

Selected public AccountTrade fill keys, in response order. Deduplicated by (instrument_id, trade_id).

Maximum array length: 4

Show child attributes

Response

Share-card snapshots with independent item statuses.

history_as_of_at

integer

required

Event time of the serving gateway's captured state and completed-history prefix, in Unix milliseconds. Missing trades are not_found at this horizon; horizons can differ by gateway.

Required range: x >= 0

active

object[]

required

Show child attributes

history

object[]

required

Show child attributes