Obchodní bot pro Polymarket Perps přes API: TypeScript a Python

Tutoriál: boti pro Polymarket · Kapitola 24 z 32

Polymarket Perps má kompletní veřejné API s oficiálními SDK pro TypeScript a Python. V této kapitole postavíme bota na skutečném rozhraní: autentizace pomocí proxy obchodního klíče, tržní data přes REST a WebSocket, příkazy s take-profit a stop-loss a řízení rizika, které zabrání botovi s pákou vyprázdnit účet.

Ad Advertise here

Autor: Harley Young, hlavní autor Polymarkets.co.il. Naposledy zkontrolováno: listopad 2026.

Co tato kapitola obsahuje

• Klíčová čísla pro tvůrce botů
• Jak je postavené Perps API
• Krok 1: instalace SDK a otevření session
• Krok 2: čtení tržních dat přes REST a WebSocket
• Krok 3: zadávání příkazů s take-profit a stop-loss
• Krok 4: kostra bota s řízením rizika v kódu
• Chyby, dead man's switch, pravidla pro boty a hosting

Každá metoda SDK a každý endpoint zde pochází z dokumentace Polymarket Perps (docs.polymarket.com/perps, čteno 6. listopadu 2026). Naše vlastní logika je označena v komentářích a funkce strategie je označený zástupný kód.

Klíčová čísla pro tvůrce botů (stav k listopadu 2026)

Jak je postavené Perps API

Perps je hybridní burza: párování příkazů probíhá offchain, úschova a vypořádání na Polygonu. Onchain jsou pouze vklady a výběry, takže za jednotlivé příkazy neplatíte žádný gas. API má tři vrstvy:

• Veřejná data (/v1/info/): instrumenty, tickery, kniha příkazů, svíčky, obchody, financování, poplatky. Nepotřebujete klíč a neplatí žádné geografické blokování.
• Soukromá čtení (/v1/account/): portfolio, zůstatky, příkazy, plnění, konfigurace.
• Podepsané zápisy (/v1/trade/): příkazy, rušení, páka, izolovaná marže, automatické rušení. Každý zápis je zakódován v MessagePack, zahashován keccak256 a podepsán proxy klíčem jako typovaná data EIP-712.

Podepisování za vás obstarají SDK. K dispozici je také specifikace OpenAPI (/api-spec/perps-openapi.json na webu dokumentace) a specifikace AsyncAPI pro WebSocket.

Krok 1: instalace SDK a otevření session

Nainstalujte pomocí pip install polymarket-client nebo npm install @polymarket/client@latest viem. Bot potřebuje adresu vaší peněženky Polymarket a privátní klíč podepisujícího účtu, kterému patří účet Perps (účet je vázán na podepisující EOA, ne na Safe). Při otevření session jednou podepíšete autorizaci nového proxy obchodního klíče, který pak podepisuje každý příkaz, takže váš klíč s prostředky nikdy neobchoduje. Uložte si session.credentials zašifrované, abyste mohli později pokračovat.

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);

Vklad z kódu (deposit_to_perps / depositToPerps) navíc vyžaduje Relayer API klíč z polymarket.com v Nastavení, API Keys. Jednodušší a bezpečnější je nabít účet ve webové aplikaci a bota k pohybu peněz vůbec nepouštět. Od 5. listopadu 2026 mohou účty s adresářem pro výběry vybírat pouze na uložené adresy. Pro dashboardy používejte klíč pouze pro čtení (proxy s označením read-only:, který odmítá podepsané zápisy), nikdy ne obchodní klíč. Ukládání klíčů popisujeme v naší kapitole o peněženkách a autentizaci.

Krok 2: čtení tržních dat přes REST a WebSocket

Ticker obsahuje tři ceny: index (férová hodnota z datových zdrojů, jako jsou Pyth, Chainlink Data Streams a Hyperliquid), mark (referenční cena pro PnL, marži, likvidaci a TP/SL) a last (pouze exekuce), k tomu sazbu financování a čas příštího financování. Signály stavějte na referenční ceně nebo indexu.

# 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);
}

Bez SDK se přihlaste k odběru na surovém WebSocketu pomocí {"id": 1, "req": "sub", "chs": ["bbo::6"]}. Kanály zahrnují bbo::<id>, book::<id>, trades::<id>, tickers::<id> a klines::<id>::1m. Každá aktualizace má pořadové číslo sq: po mezeře v číslování nebo po opětovném připojení načtěte stav znovu přes REST. Pro backtesty stránkuje historii list_perps_candles / listPerpsCandles (REST endpoint vrací až 1 000 svíček na jedno volání).

Krok 3: zadávání příkazů s take-profit a stop-loss

Příkaz má side (BUY nebo SELL), quantity v jednotkách základního aktiva, volitelnou price v pUSD a dobu platnosti (gtc, ioc nebo fok). Post-only vyžaduje GTC; reduce-only může pozici pouze zmenšit. Neexistuje příznak long nebo short: bez otevřené pozice BUY otevírá long a SELL otevírá short.

Bracket příkaz připojí ke vstupu jeden take-profit a jeden stop-loss. Zůstávají neaktivní, dokud se vstup nevyplní celý, a zruší se, pokud je vstup zrušen nebo vyplněn jen částečně. Ceny níže jsou hypotetické.

# 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);

U otevřené pozice přidá place_position_tp_sl / placePositionTpSl spouštěče, které uzavřou celou pozici. Pravidla:

• Spouštěče sledují referenční cenu (mark price) a odesílají příkaz reduce-only. Poziční TP/SL vystupuje tržně, takže v mělké knize příkazů počítejte se skluzem.
• Na každém trhu jeden poziční take-profit a jeden stop-loss. Posunutí stopu znamená zrušit a vytvořit nový, což není atomická operace.
• Spouštěč, který referenční cena už překročila, je odmítnut, a odmítnuty jsou i limitní ceny příliš vzdálené od referenční ceny.

Pokud si chcete průběh příkazu vyzkoušet ručně, než ho zautomatizujete, otevřete trh BTC na Polymarket Perps a zadejte nejmenší povolený příkaz. Když uvidíte plnění, poplatky a panel pozice, budou se vám odpovědi API číst snadněji.

Krok 4: kostra bota s řízením rizika v kódu

Kostra v Pythonu níže používá pouze zdokumentovaná volání SDK; logika řízení rizika je naše. Tři vrstvy ochrany:

1. Strop páky. Páka je nastavena na 3x nebo na maximum trhu, podle toho, co je nižší, s izolovanou marží, a velikosti, které by spadly do rizikové úrovně s nižším stropem, jsou odmítnuty.
2. Nouzové vypínače. Soubor HALT, denní limit ztráty 5 % a ukončení při likvidaci. Vypínač uzavře pozice příkazy reduce-only IOC, zruší zbývající příkazy a pak ověří, že nezůstalo ani jedno.
3. Stop na každé pozici. Vstupy fill-or-kill znamenají žádná nechráněná částečná plnění. Po každém plnění následuje poziční stop a take-profit; pokud jsou odmítnuty, pozice se okamžitě uzavře.

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())

Výpočet velikosti. Velikost se odvozuje od vzdálenosti stopu, ne od páky. Při hypotetické nabídkové ceně (ask) BTC 100 000 pUSD a stopu 2 % leží stop na 98 000. Riziko na jednotku je 2 000, takže množství je 20 / 2 000 = 0,01 BTC, tedy nominální hodnota 1 000 pUSD. Při páce 3x to vyžaduje zhruba 333 pUSD marže. Udržovací marže BTC činí 1 % (0,5 / 50x), takže likvidační cena longu je 100 000 x (1 - 1/3) / (1 - 0,01) = přibližně 67 340, tedy pokles o 32,7 %. Stop na -2 % se spustí dávno předtím. Pokud se stop vyplní na své spouštěcí ceně, ztráta je 20 pUSD plus poplatky: 0,40 za otevření a přibližně 0,39 za uzavření při taker sazbě 0,040 %, celkem tedy zhruba 20,79 pUSD před skluzem. Páka určuje jen to, kolik marže je vázáno. Ztrátu na stopu nemění.

Před ostrým spuštěním přidejte denní limit obchodů, upozornění na plnění a nouzové vypínače a srovnání stavu při startu (fetch_portfolio, fetch_open_orders, fetch_orders, list_fills). Podívejte se na naše kapitoly o kódu pro řízení rizika a cvičném obchodování, na průvodce pákou a likvidací na Perps a na průvodce sazbami financování na Perps.

Chyby, opakování a dead man's switch

• 503 service_unavailable neznamená jistě, že požadavek selhal. Čtení a změny páky opakujte s postupně se prodlužující prodlevou a respektujte Retry-After. U podepsaných změn zůstatku (marže, výběry) odešlete znovu pouze přesně původní podepsaný požadavek; nový podpis znamená druhou úpravu.
• signature expired: podpis je starší než 5 minut. Udržujte synchronizované hodiny.
• insufficient_margin / invalid_leverage: kontroly počítají s vaší pozicí plus všemi čekajícími příkazy.
• message_rate_limited: vyčerpaný limit WebSocketu. Klíče pouze pro čtení mají 1 000 zpráv za minutu na IP adresu (burst 50) a čtyři spojení na účet na gateway; zbytek najdete na stránce Rate Limits v dokumentaci.
• Chyby formátu: příliš mnoho desetinných míst nebo více než 5 platných číslic. Proto fit().

Automatické rušení zruší všechny otevřené příkazy, pokud ho bot přestane znovu aktivovat. Termín musí být alespoň 5 sekund dopředu a počet spuštění za den UTC je omezený, proto ho při řádném ukončení deaktivujte.

// 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();

Soutěže, builder kódy a pravidla pro boty

Dokumentace uvádí mezi způsoby použití API „obchodní boty, kteří reagují na tržní signály“ a market makery. Platí dvě sady pravidel.

• Soutěže. Zakázány jsou wash trading, obchodování sám se sebou, více účtů, obchodování hlavně kvůli objemu a „boti, skripty nebo automatizované prostředky určené k manipulaci s programem“. Bot, který obchoduje doopravdy, je v pořádku; bot, který jen točí objem, může být diskvalifikován.
• Builder kódy. Aplikace obchodující za jiné uživatele může se souhlasem každého obchodníka přidat poplatek až 10 bazických bodů. Musí ověřovat polohu každého uživatele a příkazy z jurisdikcí s omezením blokovat, nejen na ně upozorňovat.

Odměny za maker likviditu a soutěže popisujeme v průvodci Polymarket Perps.

Hosting bota

Bot s pákou by neměl běžet na notebooku. Musí udržovat WebSocket naživu, reagovat na plnění během několika sekund a přežít výpadek domácího internetu. Provozujte ho na VPS pod systemd s automatickým restartem, klíč mějte v souboru s proměnnými prostředí, který může číst jen uživatel bota, a synchronizujte hodiny. Zadávání příkazů není povoleno z míst s omezením, proto nehostujte v USA ani v Kanadě a nikdy nepoužívejte VPS k obcházení blokování, které se na vás vztahuje. Naše vlastní boty provozujeme na TradingVPS (affiliate odkaz: získáme malou provizi a vy zaplatíte stejnou cenu). Naše kapitola o VPS hostingu ho porovnává s dalšími poskytovateli z hlediska latence, ceny a regionů.

Po cvičném obchodování nabijte účet malou částkou ze stránky Polymarket Perps a před navyšováním nechte bota týden běžet s minimální velikostí.

Hlavní poznatky

• Používejte oficiální SDK, @polymarket/client nebo polymarket-client. Vaše peněženka podepisuje jen jednou; příkazy podepisuje proxy klíč.
• Trhy párujte podle živého symbolu (BTC-USD, ne BTC-PERP) a ukládejte číselné ID.
• Velikost odvozujte od vzdálenosti stopu, páku omezte v kódu, používejte izolovanou marži a každou pozici chraňte stopem hned po plnění.
• TP/SL se spouští podle referenční ceny a vystupuje tržně. Automatické rušení může odstranit stopy.
• Boti jsou povoleni, manipulace se soutěžemi ne. Nikdy neobchodujte ze země s omezením.

Často kladené otázky