Polymarket Perps API kereskedési bot: TypeScript és Python

Polymarket bot oktatóanyag · 24. fejezet / 32

A Polymarket Perps teljes nyilvános API-val rendelkezik, hivatalos TypeScript és Python SDK-val. Ebben a fejezetben a valódi interfészre építünk botot: hitelesítés proxy kereskedési kulccsal, piaci adatok REST-en és WebSocketen keresztül, megbízások take-profittal és stop-loss-szal, valamint azok a kockázatkezelési korlátok, amelyek megakadályozzák, hogy egy tőkeáttételes bot kiürítse a fiókot.

Ad Advertise here

Írta: Harley Young, a Polymarkets.co.il vezető szerzője. Utoljára ellenőrizve: 2026. november.

Miről szól ez a fejezet

• A legfontosabb számok botfejlesztőknek
• Hogyan épül fel a Perps API
• 1. lépés: az SDK telepítése és munkamenet nyitása
• 2. lépés: piaci adatok olvasása REST-en és WebSocketen keresztül
• 3. lépés: megbízások leadása take-profittal és stop-loss-szal
• 4. lépés: botváz kódba épített kockázatkezeléssel
• Hibák, a dead man's switch, a botokra vonatkozó szabályok és a hosztolás

Minden itt szereplő SDK-metódus és végpont a Polymarket Perps dokumentációjából származik (docs.polymarket.com/perps, 2026. november 6-án olvasva). A saját logikánkat a kommentekben jelöltük, a stratégiafüggvény pedig egy megjelölt helykitöltő.

A legfontosabb számok botfejlesztőknek (2026. novemberi állapot)

Hogyan épül fel a Perps API

A Perps hibrid tőzsde: a párosítás offchain történik, az őrzés és az elszámolás a Polygonon. Csak a befizetések és a kivételek onchain műveletek, így megbízásonként nincs gázdíj. Az API három rétegből áll:

• Nyilvános adatok (/v1/info/): instrumentumok, tickerek, ajánlati könyv, gyertyák, kötések, finanszírozási díj, díjak. Nem kell hozzá kulcs, és nincs földrajzi korlátozás.
• Privát olvasás (/v1/account/): portfólió, egyenlegek, megbízások, teljesülések, konfiguráció.
• Aláírt írás (/v1/trade/): megbízások, törlések, tőkeáttétel, elkülönített fedezet, automatikus törlés. Minden írási műveletet MessagePack formátumban kódol, keccak256-tal hashel, és EIP-712 típusos adatként ír alá a proxy kulcs.

Az aláírást az SDK-k elvégzik helyetted. Létezik OpenAPI specifikáció is (/api-spec/perps-openapi.json a dokumentációs oldalon), valamint AsyncAPI specifikáció a WebSockethez.

1. lépés: az SDK telepítése és munkamenet nyitása

Telepítsd a pip install polymarket-client vagy az npm install @polymarket/client@latest viem paranccsal. A botnak szüksége van a Polymarket-tárcád címére és annak az aláírónak a privát kulcsára, amelyhez a Perps-fiók tartozik (a fiók az aláíró EOA-hoz kötődik, nem a Safe-hez). Munkamenet nyitásakor egyszer írsz alá, ezzel engedélyezel egy új proxy kereskedési kulcsot, amely ezután minden megbízást aláír, így a befizetéshez használt kulcsod soha nem kereskedik. A session.credentials értéket titkosítva tárold, hogy később folytathasd.

import asyncio
import os
from datetime import timedelta

from polymarket import AsyncSecureClient


async def main():
    client = await AsyncSecureClient.create(
        private_key=os.environ["PRIVATE_KEY"],
        wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
    )
    # One signature creates a proxy trading key. Orders are signed by the proxy,
    # not by your wallet key. Credentials expire after one week by default.
    session = await client.open_perps_session(
        expires_in=timedelta(days=1),
        label="perps-bot",
    )
    stored = session.credentials.model_dump(mode="json")  # keep it encrypted

    instruments = await client.fetch_perps_instruments()
    btc = next(i for i in instruments if i.symbol == "BTC-USD")
    print(btc.id, btc.max_leverage, btc.min_notional, btc.price_decimals)


asyncio.run(main())

import { createSecureClient } from "@polymarket/client";
import { privateKey } from "@polymarket/client/viem";

const client = await createSecureClient({
  wallet: process.env.POLYMARKET_WALLET_ADDRESS!,
  signer: privateKey(process.env.PRIVATE_KEY!),
});

// One signature creates a proxy trading key. Orders are signed by the proxy,
// not by your wallet key. Credentials expire after one week by default.
const session = await client.openPerpsSession({
  expiresIn: 24 * 60 * 60 * 1000,
  label: "perps-bot",
});
const stored = session.credentials; // keep it encrypted

const instruments = await client.fetchPerpsInstruments();
const btc = instruments.find((i) => i.symbol === "BTC-USD");
if (!btc) throw new Error("BTC-USD not listed");
console.log(btc.id, btc.maxLeverage, btc.minNotional, btc.priceDecimals);

A kódból történő befizetéshez (deposit_to_perps / depositToPerps) Relayer API-kulcs is kell, ezt a polymarket.com Settings, API Keys menüjében kapod meg. Egyszerűbb és biztonságosabb, ha a fiókot a webes felületen töltöd fel, és a botot távol tartod a pénzmozgásoktól. 2026. november 5. óta a kivételi címjegyzéket használó fiókok csak elmentett címekre vehetnek ki pénzt. Dashboardokhoz csak olvasási kulcsot használj (ez egy read-only: címkéjű proxy, amely elutasítja az aláírt írásokat), soha ne a kereskedési kulcsot. A kulcsok tárolásáról a tárcákról és hitelesítésről szóló fejezetünkben olvashatsz.

2. lépés: piaci adatok olvasása REST-en és WebSocketen keresztül

A ticker három árat tartalmaz: index (méltányos érték olyan adatforrásokból, mint a Pyth, a Chainlink Data Streams és a Hyperliquid), jelzőár (mark, ez alapján számolódik a PnL, a fedezet, a likvidálás és a TP/SL) és utolsó ár (last, csak a végrehajtáshoz), emellett a finanszírozási rátát és a következő finanszírozás időpontját. A jelzéseidet a jelzőárra vagy az indexre építsd.

# Inside your async main(), after Step 1 (btc is the BTC-USD instrument)
from polymarket import AsyncPublicClient
from polymarket.streams import PerpsBboSpec

client = AsyncPublicClient()

ticker = await client.fetch_perps_ticker(instrument_id=btc.id)
print(ticker.mark_price, ticker.index_price, ticker.funding_rate)

stream = await client.subscribe(PerpsBboSpec(instrument_id=btc.id))
async for event in stream:
    print(event.payload.bid_price, event.payload.ask_price)

// After Step 1 (btc is the BTC-USD instrument)
import { createPublicClient } from "@polymarket/client";

const client = createPublicClient();

const ticker = await client.fetchPerpsTicker({ instrumentId: btc.id });
console.log(ticker.markPrice, ticker.indexPrice, ticker.fundingRate);

const stream = await client.subscribe([{ topic: "perps.bbo", instrumentId: btc.id }]);
for await (const event of stream) {
  console.log(event.payload.bidPrice, event.payload.askPrice);
}

SDK nélkül a nyers WebSocketen így iratkozhatsz fel: {"id": 1, "req": "sub", "chs": ["bbo::6"]}. Elérhető csatornák többek között: bbo::<id>, book::<id>, trades::<id>, tickers::<id> és klines::<id>::1m. Minden frissítésnek van egy sq sorszáma: kimaradás vagy újracsatlakozás után olvasd újra az állapotot REST-en. Backtesthez a list_perps_candles / listPerpsCandles lapozva adja vissza az előzményeket (a REST végpont hívásonként legfeljebb 1 000 gyertyát ad).

3. lépés: megbízások leadása take-profittal és stop-loss-szal

Egy megbízásnak van side iránya (BUY vagy SELL), quantity mennyisége az alapeszköz egységében, opcionális price ára pUSD-ben, és érvényességi ideje (gtc, ioc vagy fok). A post-only megbízáshoz GTC kell; a reduce-only csak csökkentheti a pozíciót. Nincs külön long vagy short jelző: nyitott pozíció nélkül a BUY longot, a SELL shortot nyit.

A bracket megbízás egy take-profitot és egy stop-losst csatol a belépő megbízáshoz. Ezek addig inaktívak, amíg a belépés teljesen nem teljesül, és törlődnek, ha a belépőt törlik, vagy csak részben teljesül. Az alábbi árak csak szemléltetők.

# Inside your async main(), after Step 1 (btc is the BTC-USD instrument)
from polymarket import PerpsTpSlTrigger

result = await session.place_order(
    instrument_id=btc.id,
    side="BUY",
    price="100000",
    quantity="0.01",
    time_in_force="gtc",
    take_profit=PerpsTpSlTrigger(trigger_price="104000"),
    stop_loss=PerpsTpSlTrigger(trigger_price="98000"),
)
print(result.order.id, result.order.status)

// After Step 1 (btc is the BTC-USD instrument)
import { OrderSide, PerpsTimeInForce } from "@polymarket/client";

const result = await session.placeOrder({
  instrumentId: btc.id,
  side: OrderSide.BUY,
  price: "100000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.GTC,
  takeProfit: { triggerPrice: "104000" },
  stopLoss: { triggerPrice: "98000" },
});
console.log(result.order.id, result.tpSl.stopLoss?.orderId);

Nyitott pozícióhoz a place_position_tp_sl / placePositionTpSl olyan triggereket ad, amelyek a teljes pozíciót zárják. Szabályok:

• A triggerek a jelzőárat figyelik, és reduce-only megbízást küldenek. A pozíciószintű TP/SL piaci áron zár, ezért vékony ajánlati könyvben számíts csúszásra.
• Piaconként egy pozíciószintű take-profit és egy stop-loss lehet. A stop áthelyezése törlést, majd új létrehozását jelenti, ami nem atomi művelet.
• Az a trigger, amelyen a jelzőár már túlment, elutasításra kerül, és a jelzőártól túl messze lévő limitárakat is visszautasítja a rendszer.

Ha automatizálás előtt kézzel szeretnéd kipróbálni a megbízási folyamatot, nyisd meg a BTC piacot a Polymarket Perpsen, és adj le egy minimális méretű megbízást. Ha látod a teljesüléseket, a díjakat és a pozíciópanelt, könnyebben értelmezed az API válaszait.

4. lépés: botváz kódba épített kockázatkezeléssel

Az alábbi Python váz kizárólag dokumentált SDK-hívásokat használ; a kockázatkezelési logika a miénk. A védelem három rétegű:

1. Tőkeáttételi plafon. A tőkeáttétel 3x vagy a piaci maximum, amelyik alacsonyabb, elkülönített fedezettel, és a rendszer visszautasítja azokat a méreteket, amelyek alacsonyabb plafonú kockázati sávba esnének.
2. Vészleállítók. Egy HALT fájl, 5%-os napi veszteségkorlát és kilépés likvidáláskor. A vészleállító reduce-only IOC megbízásokkal zárja a pozíciókat, törli a maradék megbízásokat, majd ellenőrzi, hogy mindkettő eltűnt-e.
3. Stop minden pozíción. A fill-or-kill belépők miatt nincs védelem nélküli részteljesülés. Minden teljesülés után pozíciószintű stop és take-profit következik; ha ezeket elutasítják, a pozíció azonnal zárul.

import asyncio
import logging
import os
from datetime import timedelta
from decimal import Decimal, ROUND_DOWN

from polymarket import AsyncSecureClient, PerpsPositionTpSlTrigger

SYMBOL = "BTC-USD"                   # live API symbol; docs examples say "BTC-PERP"
LEVERAGE_CAP = 3                     # our cap, far below the 50x BTC allows
RISK_PER_TRADE = Decimal("20")       # pUSD we accept losing if the stop fills
STOP_PCT = Decimal("0.02")           # stop 2% from entry
TAKE_PCT = Decimal("0.04")           # take profit 4% from entry
MAX_NOTIONAL = Decimal("2000")       # hard cap per position, in pUSD
MAX_SLIPPAGE = Decimal("0.002")      # worst entry price: ask + 0.2%
MAX_FUNDING = Decimal("0.0005")      # skip longs if funding > 0.05% per hour
DAILY_LOSS_LIMIT = Decimal("0.05")   # kill switch at -5% of start equity
HALT_FILE = "/opt/perps-bot/HALT"    # touch this file to stop the bot


def fit(value: Decimal, decimals: int, sig: int = 5) -> str:
    """Round down to the market's decimals and to 5 significant figures."""
    v = value.quantize(Decimal(1).scaleb(-decimals), rounding=ROUND_DOWN)
    if v != 0:
        step = Decimal(1).scaleb(v.adjusted() - sig + 1)
        if step > Decimal(1).scaleb(-decimals):
            v = v.quantize(step, rounding=ROUND_DOWN)
    return format(v, "f")


def tier_cap(inst, notional: Decimal) -> int:
    """Max leverage allowed for this notional by the market's risk tiers."""
    cap = inst.max_leverage
    for tier in inst.risk_tiers:
        if notional >= Decimal(tier.lower_bound):
            cap = tier.max_leverage
    return cap


async def close_all(session):
    """Close every position with reduce-only IOC orders, then cancel the rest."""
    portfolio = await session.fetch_portfolio()
    for pos in portfolio.positions:
        if pos.size != 0:
            await session.place_order(
                instrument_id=pos.instrument_id,
                side="SELL" if pos.size > 0 else "BUY",
                quantity=abs(pos.size),
                time_in_force="ioc",
                reduce_only=True,
            )
    await session.cancel_all_orders()


async def kill_switch(session, reason: str):
    logging.error("KILL SWITCH: %s", reason)
    for attempt in range(3):
        await close_all(session)
        portfolio = await session.fetch_portfolio()
        open_orders = await session.fetch_open_orders()
        if not open_orders and all(p.size == 0 for p in portfolio.positions):
            return
        await asyncio.sleep(2)
    logging.critical("Positions still open after kill switch: act manually")


async def open_long(client, session, inst):
    ticker = await client.fetch_perps_ticker(instrument_id=inst.id)
    if Decimal(ticker.funding_rate) > MAX_FUNDING:
        return                                     # longs would pay too much
    book = await client.fetch_perps_book(instrument_id=inst.id, depth=10)
    if not book.asks:
        return
    ask = Decimal(book.asks[0].price)
    stop = ask * (1 - STOP_PCT)
    qty = RISK_PER_TRADE / (ask - stop)            # size from the stop, not leverage
    qty = min(qty, MAX_NOTIONAL / ask)
    notional = qty * ask
    if notional < Decimal(inst.min_notional):
        return
    if tier_cap(inst, notional) < LEVERAGE_CAP:
        return                                     # size would break our cap

    entry = await session.place_order(
        instrument_id=inst.id,
        side="BUY",
        price=fit(ask * (1 + MAX_SLIPPAGE), inst.price_decimals),
        quantity=fit(qty, inst.quantity_decimals),
        time_in_force="fok",                       # all or nothing
    )
    if entry.order.status != "filled":
        return

    try:                                           # stop on the whole position
        await session.place_position_tp_sl(
            instrument_id=inst.id,
            take_profit=PerpsPositionTpSlTrigger(
                trigger_price=fit(ask * (1 + TAKE_PCT), inst.price_decimals)),
            stop_loss=PerpsPositionTpSlTrigger(
                trigger_price=fit(stop, inst.price_decimals)),
        )
    except Exception:
        logging.exception("TP/SL rejected: closing the unprotected position")
        await close_all(session)


async def my_signal(client, inst) -> bool:
    """PLACEHOLDER: your strategy goes here. Not part of the SDK."""
    return False


async def main():
    logging.basicConfig(level=logging.INFO)
    client = await AsyncSecureClient.create(
        private_key=os.environ["PRIVATE_KEY"],
        wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
    )
    session = await client.open_perps_session(
        expires_in=timedelta(days=1), label="perps-bot")
    inst = next(i for i in await client.fetch_perps_instruments()
                if i.symbol == SYMBOL)

    # Control 1: leverage cap and isolated margin, set before any order
    await session.update_leverage(
        instrument_id=inst.id,
        leverage=min(LEVERAGE_CAP, inst.max_leverage),
        cross_margin=False,
    )

    # Field names below follow the documented portfolio JSON
    # (margin.total_account_value, in_liquidation). Check them in your SDK.
    start_equity = Decimal((await session.fetch_portfolio()).margin.total_account_value)

    while True:
        portfolio = await session.fetch_portfolio()
        equity = Decimal(portfolio.margin.total_account_value)

        # Control 2: kill switches
        if os.path.exists(HALT_FILE):
            await kill_switch(session, "HALT file found")
            break
        if equity < start_equity * (1 - DAILY_LOSS_LIMIT):
            await kill_switch(session, f"daily loss limit hit: {equity}")
            break
        if portfolio.in_liquidation:
            await kill_switch(session, "account in liquidation")
            break

        in_position = any(p.instrument_id == inst.id and p.size != 0
                          for p in portfolio.positions)
        if not in_position and await my_signal(client, inst):
            await open_long(client, session, inst)   # Control 3 lives here

        await asyncio.sleep(5)


asyncio.run(main())

A méretezés matematikája. A pozícióméret a stop távolságából adódik, nem a tőkeáttételből. Egy feltételezett 100 000 pUSD-s BTC eladási árnál és 2%-os stopnál a stop 98 000-en van. Az egységenkénti kockázat 2 000, így a mennyiség 20 / 2 000 = 0,01 BTC, ami 1 000 pUSD névérték. 3x tőkeáttétellel ehhez nagyjából 333 pUSD fedezet kell. A BTC fenntartási fedezeti rátája 1% (0,5 / 50x), így a long likvidálási ára 100 000 x (1 - 1/3) / (1 - 0,01) = kb. 67 340, ami 32,7%-os esés. A -2%-os stop jóval előtte aktiválódik. Ha a stop a trigger áron teljesül, a veszteség 20 pUSD plusz díjak: 0,40 a nyitásnál és kb. 0,39 a zárásnál a 0,040%-os taker díjjal, összesen tehát kb. 20,79 pUSD csúszás nélkül. A tőkeáttétel csak azt határozza meg, mennyi fedezet van lekötve. A stopnál keletkező veszteségen nem változtat.

Élesítés előtt adj hozzá napi kereskedési korlátot, riasztásokat teljesülésekre és vészleállításokra, valamint induláskori egyeztetést (fetch_portfolio, fetch_open_orders, fetch_orders, list_fills). Nézd meg a kockázatkezelési kódról és a gyakorló kereskedésről szóló fejezeteinket, a Perps tőkeáttételi és likvidálási útmutatót, valamint a Perps finanszírozási ráták útmutatót.

Hibák, újrapróbálkozások és a dead man's switch

• 503 service_unavailable: ez nem bizonyítja, hogy a kérés sikertelen volt. Az olvasásokat és a tőkeáttétel-módosításokat fokozatosan növekvő várakozással próbáld újra, és tartsd be a Retry-After értékét. Aláírt egyenlegmódosításoknál (fedezet, kivétel) csak a pontosan azonos, eredeti aláírt kérést küldd újra; egy új aláírás második módosításnak számít.
• signature expired: 5 percnél régebbi. Tartsd szinkronban az órát.
• insufficient_margin / invalid_leverage: az ellenőrzés a pozíciódat és az összes függő megbízásodat is figyelembe veszi.
• message_rate_limited: elfogyott a WebSocket-keret. A csak olvasási kulcsok IP-nként percenként 1 000 üzenetet kapnak (burst 50), és fiókonként, gatewayenként négy kapcsolatot; a többit a dokumentáció Rate Limits oldalán találod.
• Formátumhibák: túl sok tizedesjegy vagy 5-nél több értékes jegy. Ezért van a fit().

Az automatikus törlés (auto-cancel) minden nyitott megbízást töröl, ha a botod abbahagyja az újraélesítését. A határidőnek legalább 5 másodperccel előrébb kell lennie, és a UTC naponkénti aktiválások száma korlátozott, ezért szabályos leállításkor kapcsold ki.

// For quoting bots: cancel all resting orders if this process dies
await session.armAutoCancel({ cancelAt: Date.now() + 60_000 });
const rearm = setInterval(() => {
  // A missed re-arm is fail-safe: the armed switch still fires.
  session.armAutoCancel({ cancelAt: Date.now() + 60_000 }).catch(console.error);
}, 20_000);

// On a clean shutdown
clearInterval(rearm);
await session.disarmAutoCancel();

Versenyek, builder kódok és a botokra vonatkozó szabályok

A dokumentáció az API felhasználási módjai között említi a „piaci jelzésekre reagáló kereskedési botokat” és az árjegyzőket. Kétféle szabályrendszer vonatkozik rájuk.

• Versenyek. Tilos a wash trading, az önmagaddal való kereskedés, a több fiók használata, a főként forgalomgenerálás céljából végzett kereskedés, valamint a „Program manipulálására szolgáló botok, szkriptek vagy automatizált eszközök”. A valóban kereskedő bot rendben van; a forgalmat pörgető bot kizárást vonhat maga után.
• Builder kódok. Egy más felhasználók nevében kereskedő alkalmazás legfeljebb 10 bázispontos díjat számíthat fel, minden kereskedő jóváhagyásával. Minden felhasználó tartózkodási helyét ellenőriznie kell, és a korlátozott joghatóságokból érkező megbízásokat blokkolnia kell, nem elég figyelmeztetnie.

A maker likviditási jutalmakról és a versenyekről a Polymarket Perps útmutatóban olvashatsz.

A bot hosztolása

Tőkeáttételes bot ne laptopon fusson. Életben kell tartania a WebSocket-kapcsolatot, másodpercek alatt reagálnia kell a teljesülésekre, és túl kell élnie az otthoni internet kiesését. Futtasd VPS-en systemd alatt, automatikus újraindítással, a kulcsot tartsd olyan környezeti fájlban, amelyet csak a bot felhasználója olvashat, és szinkronizáld az órát. Korlátozott helyekről nem lehet megbízást leadni, ezért ne hosztolj az Egyesült Államokban vagy Kanadában, és soha ne használj VPS-t egy rád vonatkozó korlátozás megkerülésére. A saját botjainkat a TradingVPS-en futtatjuk (partnerlink: kis jutalékot kapunk, neked ugyanannyiba kerül). A VPS-hosztolásról szóló fejezetünk késleltetés, ár és régiók szerint hasonlítja össze más szolgáltatókkal.

Gyakorló kereskedés után tölts fel kis összeget a fiókra a Polymarket Perps oldalán, és egy hétig minimális mérettel fuss, mielőtt növelnéd.

A legfontosabb tanulságok

• Használd a hivatalos SDK-kat, a @polymarket/client vagy a polymarket-client csomagot. A tárcád egyszer ír alá; a megbízásokat egy proxy kulcs írja alá.
• A piacokat az élő szimbólum alapján párosítsd (BTC-USD, nem BTC-PERP), és a numerikus azonosítót tárold el.
• A méretet a stop távolságából számold, a tőkeáttételt kódban korlátozd, használj elkülönített fedezetet, és minden pozícióra azonnal a teljesülés után tegyél stopot.
• A TP/SL a jelzőárra reagál, és piaci áron zár. Az automatikus törlés eltávolíthatja a stopokat.
• A botok megengedettek, a versenyek manipulálása nem. Soha ne kereskedj korlátozott országból.

Gyakran ismételt kérdések