Skip to main content
PMXT runs two ways. Hosted is the default — it’s what pmxt.Polymarket(pmxt_api_key=...) does when an API key is set. Self-hosted is the advanced escape hatch — you run pmxt-core on your own machine and the SDK talks to localhost. Both expose the same SDK surface; the difference is where execution happens and who holds keys.

​
At a glance

Hosted (pmxt_api_key set)Self-hosted (no API key)
Install footprintpip install pmxt / npm i pmxtjsSDK + pmxt-core local server
Who holds the API key?You (backend secret)Not used
Who holds venue credentials?PMXT escrow contract (USDC custody only)You, on your machine
Trading auth (writes)Your EIP-712 signature, signed locallyRaw venue credential (private key, Kalshi RSA, etc.)
Readstrade.pmxt.dev/v0/user/...Direct to the venue API
Writestrade.pmxt.dev/v0/trade/{build,submit}-orderDirect to the venue API
CustodyUSDC in PMXT PreFundedEscrowYou retain venue-native custody
Latency~150–300ms round-tripLimited by venue + your network
Trading venuesPolymarket, OpinionEvery venue PMXT supports
Read-only venuesAll catalog venues via RouterAll catalog venues via Router
Infra to runNoneOne local process
Regulatory custodyPMXT escrow as counterpartyYou as direct counterparty to the venue

​
When hosted is the right choice

  • You’re building a web or mobile app and want to keep pmxt_api_key server-side while end users keep their private keys client-side.
  • You want one HTTP surface across Polymarket and Opinion without learning each venue’s order schema.
  • You want PreFundedEscrow custody instead of managing venue-native accounts.
  • You don’t want to operate the pmxt-core process, manage upgrades, or run a local PMXT service.

​
When self-hosted is the right choice

  • You need sub-100ms latency — colocated arbitrage, market-making, latency-sensitive HFT-style strategies.
  • You prefer raw venue credentials — Polymarket L2 API keys, Kalshi RSA keys, Smarkets sessions — and don’t want PMXT in the custody path.
  • You have regulatory custody requirements that mandate direct counterparty status with the venue.
  • You want to trade on venues not yet supported by hosted (Kalshi, Limitless, Smarkets, Probable, Myriad, etc.).
  • You’re an OSS contributor developing or debugging pmxt-core itself.
See Self-hosted for setup.

​
What’s identical either way

The SDK surface is the same. Code written against hosted will run against self-hosted with no changes except dropping the pmxt_api_key argument: 
# Hosted (default)
client = pmxt.Polymarket(pmxt_api_key="pmxt_live_...", wallet_address="0x...", private_key="0x...")

# Self-hosted (drop the API key — talks to http://localhost:3847)
client = pmxt.Polymarket(private_key="0x...")
fetch_markets, fetch_order_book, create_order, fetch_positions — same signatures, same response shapes.

​
What differs subtly

  • fetch_balance: hosted returns escrow USDC; self-hosted returns the venue-native balance (e.g. Polymarket’s CLOB-proxy USDC). Same shape, different source. See the migration guide for the implications.
  • Position fields: hosted may surface None/undefined on entry_price, current_price, unrealized_pnl, outcome_label when the server doesn’t yet have the data. Self-hosted always populates them.
  • Catalog UUIDs vs venue IDs: hosted-mode create_order requires catalog UUIDs (market_id, outcome_id). Self-hosted accepts the venue-native ID directly. See Catalog UUID vs venue ID.
  • Error classes: hosted produces HostedTradingError subclasses with semantic parents (InsufficientEscrowBalance is also InsufficientFunds). Self-hosted produces the parent classes directly. Catch the parent and you handle both paths. See Hosted errors.

​
Mixing modes

You can run hosted reads with self-hosted writes (or vice versa) — they’re independent SDK instances. A common pattern is: 
# Hosted client for cross-venue research
hosted = pmxt.Polymarket(pmxt_api_key="pmxt_live_...")
markets = hosted.fetch_markets(query="election")

# Self-hosted client for trading with raw venue creds
local = pmxt.Polymarket(private_key="0x...")
order = local.create_order(...)
This is useful if you trust PMXT enough for catalog and price data but want custody to stay with the venue for execution.