Polymarket Perps API İşlem Botu: TypeScript ve Python

Polymarket bot eğitimi · Bölüm 24 / 32

Polymarket Perps, resmi TypeScript ve Python SDK'larıyla birlikte herkese açık, tam kapsamlı bir API sunar. Bu bölümde gerçek arayüz üzerinde bir bot geliştiriyoruz: proxy işlem anahtarıyla kimlik doğrulama, REST ve WebSocket üzerinden piyasa verileri, kâr al (take-profit) ve zarar durdur (stop-loss) içeren emirler ve kaldıraçlı bir botun hesabı boşaltmasını önleyen risk kontrolleri.

Reklam Burada reklam verin

Yazar: Harley Young, Polymarkets.co.il baş yazarı. Son inceleme: Kasım 2026.

Bu bölümün kapsamı

• Bot geliştiriciler için temel rakamlar
• Perps API'nin yapısı
• Adım 1: SDK'yı kurun ve bir oturum açın
• Adım 2: piyasa verilerini REST ve WebSocket üzerinden okuyun
• Adım 3: kâr al ve zarar durdur içeren emirler verin
• Adım 4: risk kontrolleri kodun içinde olan bir bot iskeleti
• Hatalar, ölü adam anahtarı, botlar için kurallar ve barındırma

Buradaki her SDK metodu ve endpoint, Polymarket'in Perps dokümantasyonundan alınmıştır (docs.polymarket.com/perps, 6 Kasım 2026'da okundu). Kendi mantığımız yorum satırlarında belirtilmiştir. Strateji fonksiyonu ise etiketli bir yer tutucudur.

Bot geliştiriciler için temel rakamlar (Kasım 2026 itibarıyla)

Perps API'nin yapısı

Perps hibrit bir borsadır: eşleştirme zincir dışında (offchain), varlık saklama ve uzlaşma ise Polygon üzerinde gerçekleşir. Yalnızca para yatırma ve çekme işlemleri zincir üzerindedir (onchain), bu nedenle emir başına gas ücreti yoktur. API üç katmandan oluşur:

• Herkese açık veriler (/v1/info/): enstrümanlar, ticker'lar, emir defteri, mumlar, işlemler, fonlama, işlem ücretleri. Anahtar gerekmez ve coğrafi engel yoktur.
• Özel okumalar (/v1/account/): portföy, bakiyeler, emirler, gerçekleşmeler, yapılandırma.
• İmzalı yazma işlemleri (/v1/trade/): emirler, iptaller, kaldıraç, izole teminat, otomatik iptal. Her yazma işlemi MessagePack ile kodlanır, keccak256 ile hash'lenir ve proxy anahtarıyla EIP-712 typed data olarak imzalanır.

İmzalamayı SDK'lar sizin yerinize yapar. Ayrıca bir OpenAPI şartnamesi (dokümantasyon sitesinde /api-spec/perps-openapi.json) ve WebSocket için bir AsyncAPI şartnamesi de bulunur.

Adım 1: SDK'yı kurun ve bir oturum açın

Kurulum için pip install polymarket-client veya npm install @polymarket/client@latest viem komutunu kullanın. Botun, Polymarket cüzdan adresinize ve Perps hesabının sahibi olan imzalayıcının özel anahtarına ihtiyacı vardır (hesap Safe'e değil, imzalayıcı EOA'ya bağlıdır). Oturum açarken yeni bir proxy işlem anahtarını yetkilendirmek için tek seferlik bir imza atılır. Bu anahtar daha sonra her emri imzalar, böylece fon anahtarınız hiçbir zaman işlem yapmaz. Daha sonra kaldığınız yerden devam edebilmek için session.credentials değerini şifreli olarak saklayın.

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

Koddan para yatırmak (deposit_to_perps / depositToPerps) için ayrıca polymarket.com'da Ayarlar, API Anahtarları bölümünden alınan bir Relayer API anahtarı gerekir. Daha basit ve daha güvenli yol: hesabı web uygulamasından fonlayın ve botu para hareketlerinden uzak tutun. 5 Kasım 2026'dan bu yana, para çekme adres defterini kullanan hesaplar yalnızca kayıtlı adreslere para çekebilir. Panolar için işlem anahtarını asla kullanmayın, bunun yerine bir salt okunur anahtar kullanın (read-only: etiketli, imzalı yazma işlemlerini reddeden bir proxy). Anahtar saklama konusu cüzdanlar ve kimlik doğrulama bölümümüzde ele alınıyor.

Adım 2: piyasa verilerini REST ve WebSocket üzerinden okuyun

Ticker'da üç fiyat bulunur: endeks (Pyth, Chainlink Data Streams ve Hyperliquid gibi veri akışlarından gelen adil değer), işaret (PnL, teminat, likidasyon ve TP/SL için kullanılır) ve son (yalnızca gerçekleşen işlemler). Bunlara ek olarak fonlama oranı ve bir sonraki fonlama zamanı da yer alır. Sinyallerinizi işaret veya endeks fiyatına dayandırın.

# 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 kullanmadan, ham WebSocket üzerinde {"id": 1, "req": "sub", "chs": ["bbo::6"]} ile abone olabilirsiniz. Kanallar arasında bbo::<id>, book::<id>, trades::<id>, tickers::<id> ve klines::<id>::1m bulunur. Her güncellemenin bir sıra numarası (sq) vardır: bir boşluk veya yeniden bağlanma sonrasında durumu REST üzerinden yeniden okuyun. Geriye dönük testler için list_perps_candles / listPerpsCandles geçmiş verileri sayfalar halinde getirir (REST endpoint'i çağrı başına en fazla 1.000 mum döndürür).

Adım 3: kâr al ve zarar durdur içeren emirler verin

Bir emrin bir yönü (side: BUY veya SELL), temel varlık biriminde bir miktarı (quantity), pUSD cinsinden isteğe bağlı bir fiyatı (price) ve bir geçerlilik süresi (gtc, ioc veya fok) vardır. Post-only için GTC gerekir; reduce-only ise yalnızca bir pozisyonu küçültebilir. Ayrı bir long veya short bayrağı yoktur: pozisyon yokken BUY bir long, SELL bir short pozisyon açar.

Bir bracket emri, giriş emrine bir kâr al ve bir zarar durdur ekler. Bunlar giriş emri tamamen gerçekleşene kadar pasif kalır; giriş iptal edilirse veya yalnızca kısmen gerçekleşirse iptal edilir. Aşağıdaki fiyatlar varsayımsaldır.

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

Açık bir pozisyon için place_position_tp_sl / placePositionTpSl, pozisyonun tamamını kapatan tetikleyiciler ekler. Kurallar:

• Tetikleyiciler işaret fiyatını izler ve reduce-only bir emir gönderir. Pozisyon TP/SL'si piyasa fiyatından çıkış yapar, bu yüzden sığ emir defterlerinde kayma bekleyin.
• Her piyasada bir pozisyon kâr al ve bir zarar durdur olabilir. Bir stop'u taşımak önce iptal edip sonra yeniden oluşturmak demektir ve bu işlem atomik değildir.
• İşaret fiyatının zaten geçtiği bir tetikleyici reddedilir; işaret fiyatından çok uzak limit fiyatları da kabul edilmez.

Otomatikleştirmeden önce emir akışını elle denemek için Polymarket Perps'teki BTC piyasasını açın ve izin verilen en küçük emri verin. Gerçekleşmeleri, işlem ücretlerini ve pozisyon panelini görmek API yanıtlarını okumayı kolaylaştırır.

Adım 4: risk kontrolleri kodun içinde olan bir bot iskeleti

Aşağıdaki Python iskeleti yalnızca dokümante edilmiş SDK çağrılarını kullanır; risk mantığı bize aittir. Üç koruma katmanı vardır:

1. Kaldıraç sınırı. Kaldıraç, izole teminatla 3x veya piyasa maksimumundan hangisi düşükse ona ayarlanır. Daha düşük kaldıraç sınırlı bir risk kademesine düşen boyutlar reddedilir.
2. Acil durdurma anahtarları. Bir HALT dosyası, %5'lik günlük zarar limiti ve likidasyon durumunda çıkış. Anahtar, pozisyonları reduce-only IOC emirleriyle kapatır, kalan emirleri iptal eder, ardından ikisinin de kalmadığını kontrol eder.
3. Her pozisyonda bir stop. Fill-or-kill girişler sayesinde korumasız kısmi gerçekleşme olmaz. Her gerçekleşmenin ardından bir pozisyon stop'u ve kâr al eklenir; bunlar reddedilirse pozisyon hemen kapatılır.

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

Boyutlandırma hesabı. Boyut kaldıraçtan değil, stop mesafesinden belirlenir. Varsayımsal olarak BTC satış fiyatı 100.000 pUSD ve stop %2 ise, stop 98.000'dedir. Birim başına risk 2.000 olduğundan miktar 20 / 2.000 = 0,01 BTC, nominal değer ise 1.000 pUSD olur. 3x kaldıraçla bunun için yaklaşık 333 pUSD teminat gerekir. BTC'nin sürdürme teminatı oranı %1'dir (0,5 / 50x), bu yüzden long pozisyonun likidasyon fiyatı 100.000 x (1 - 1/3) / (1 - 0,01) = yaklaşık 67.340, yani %32,7'lik bir düşüştür. -%2'deki stop bundan çok önce tetiklenir. Stop tetik fiyatından gerçekleşirse zarar 20 pUSD artı işlem ücretleridir: %0,040'lık taker oranıyla açılışta 0,40 ve kapanışta yaklaşık 0,39, yani kayma hariç toplam yaklaşık 20,79 pUSD. Kaldıraç yalnızca ne kadar teminatın bağlanacağını belirler. Stop'taki zararı değiştirmez.

Canlıya geçmeden önce günlük işlem limiti, gerçekleşmeler ve acil durdurma anahtarları için uyarılar ve başlangıçta bir mutabakat adımı (fetch_portfolio, fetch_open_orders, fetch_orders, list_fills) ekleyin. Risk kodu ve paper trading bölümlerimize, Perps kaldıraç ve likidasyon rehberine ve Perps fonlama oranları rehberine göz atın.

Hatalar, yeniden denemeler ve ölü adam anahtarı (dead man's switch)

• 503 service_unavailable isteğin başarısız olduğunu kanıtlamaz. Okumaları ve kaldıraç değişikliklerini geri çekilme (backoff) ile yeniden deneyin ve Retry-After başlığına uyun. İmzalı bakiye değişikliklerinde (teminat, para çekme) yalnızca orijinal imzalı isteğin birebir aynısını yeniden gönderin; yeni bir imza ikinci bir düzenleme anlamına gelir.
• signature expired: imza 5 dakikadan eski. Sistem saatini senkronize tutun.
• insufficient_margin / invalid_leverage: kontroller pozisyonunuzu ve bekleyen tüm emirleri birlikte hesaba katar.
• message_rate_limited: WebSocket kotası tükendi. Salt okunur anahtarlar IP başına dakikada 1.000 mesaj (anlık 50) ve gateway başına hesap başına dört bağlantı hakkına sahiptir; geri kalanı için dokümantasyondaki Rate Limits sayfasına bakın.
• Format hataları: çok fazla ondalık basamak veya 5'ten fazla anlamlı basamak. fit() fonksiyonu bu yüzden var.

Otomatik iptal (auto-cancel), botunuz onu yeniden kurmayı bırakırsa tüm açık emirleri iptal eder. Son tarih en az 5 saniye ileride olmalıdır ve UTC günü başına tetikleme sayısı sınırlıdır, bu yüzden temiz bir kapanışta özelliği devre dışı bırakın.

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

Yarışmalar, builder kodları ve botlar için kurallar

Dokümantasyon, API'nin kullanım alanları arasında "piyasa sinyallerine tepki veren işlem botlarını" ve piyasa yapıcıları sayar. İki ayrı kural seti geçerlidir.

• Yarışmalar. Wash trading, kendi kendine işlem (self-trading), birden fazla hesap kullanmak, esas olarak işlem hacmi için işlem yapmak ve "Programı manipüle etmeye yönelik botlar, scriptler veya otomatik araçlar" yasaktır. Gerçek işlemler yapan bir bot sorun değildir; yalnızca hacim şişiren bir bot diskalifiye edilebilir.
• Builder kodları. Başka kullanıcılar adına işlem yapan bir uygulama, her kullanıcının onayıyla en fazla 10 baz puanlık bir ücret ekleyebilir. Uygulama her kullanıcının konumunu doğrulamalı ve kısıtlı yargı bölgelerinden gelen emirleri yalnızca uyarmakla yetinmeyip engellemelidir.

Maker likidite ödülleri ve yarışmalar Polymarket Perps rehberinde ele alınmıştır.

Botu barındırma

Kaldıraçlı bir bot dizüstü bilgisayarda çalışmamalıdır. WebSocket bağlantısını canlı tutmalı, gerçekleşmelere saniyeler içinde tepki vermeli ve evdeki internet kesintilerinden etkilenmemelidir. Botu otomatik yeniden başlatmalı olarak systemd altında bir VPS'te çalıştırın, anahtarı yalnızca bot kullanıcısının okuyabildiği bir ortam dosyasında tutun ve sistem saatini senkronize edin. Emirlerin kısıtlı konumların içinden verilmesine izin verilmez, bu yüzden botu ABD'de veya Kanada'da barındırmayın ve size uygulanan bir engeli aşmak için asla VPS kullanmayın. Kendi botlarımızı TradingVPS üzerinde çalıştırıyoruz (ortaklık bağlantısı: küçük bir komisyon kazanıyoruz, sizin ödediğiniz fiyat değişmez). VPS barındırma bölümümüz bu hizmeti gecikme, fiyat ve bölgeler açısından diğer sağlayıcılarla karşılaştırıyor.

Paper trading aşamasından sonra hesabı Polymarket Perps sayfasından küçük bir tutarla fonlayın ve ölçeği büyütmeden önce botu bir hafta boyunca minimum boyutla çalıştırın.

Önemli çıkarımlar

• Resmi SDK'ları kullanın: @polymarket/client veya polymarket-client. Cüzdanınız yalnızca bir kez imza atar; emirleri bir proxy anahtarı imzalar.
• Piyasaları canlı sembol üzerinden eşleştirin (BTC-USD, BTC-PERP değil) ve sayısal ID'yi saklayın.
• Boyutu stop mesafesine göre belirleyin, kaldıracı kodda sınırlayın, izole teminat kullanın ve her pozisyona gerçekleşmenin hemen ardından stop koyun.
• TP/SL işaret fiyatına göre tetiklenir ve piyasa fiyatından çıkış yapar. Otomatik iptal stop'ları kaldırabilir.
• Botlara izin verilir, yarışmaları manipüle etmeye izin verilmez. Asla kısıtlı bir ülkeden işlem yapmayın.

Sıkça sorulan sorular