Complete reference documentation for all Protocol Buffer messages, fields, and enumerations used in the gRPC streaming API.
Available Services The Polymarket Exchange API exposes the following gRPC services:
Service Description polymarket.v1.MarketDataSubscriptionAPIReal-time market data streaming polymarket.v1.OrderEntryAPIOrder submission and streaming polymarket.v1.OrderAPIOrder search and history polymarket.v1.PositionAPIPosition and balance queries polymarket.v1.AccountsAPIAccount information polymarket.v1.MarketDataAPIInstrument and symbol data polymarket.v1.DropCopyAPIExecution feed polymarket.v1.KYCAPIKYC verification polymarket.v1.AeropayAPIACH payments polymarket.v1.CheckoutAPICard payments polymarket.v1.FundingAPIFunding management polymarket.v1.HealthAPIHealth check
Obtaining Proto Files Option 1: Request Proto Files (Recommended)
Request Proto Files Contact the Polymarket API team to request the proto definitions package.
Option 2: gRPC Server Reflection Use gRPC reflection to discover services at runtime. Install grpcurl first.
# List all services grpcurl -authority grpc-prod.polymarketexchange.com grpc-prod.polymarketexchange.com:443 list # Example output: # polymarket.v1.AccountsAPI # polymarket.v1.AeropayAPI # polymarket.v1.MarketDataSubscriptionAPI # polymarket.v1.OrderEntryAPI # ... # Describe a specific service grpcurl -authority grpc-prod.polymarketexchange.com grpc-prod.polymarketexchange.com:443 \ describe polymarket.v1.MarketDataSubscriptionAPI # Describe a message type grpcurl -authority grpc-prod.polymarketexchange.com grpc-prod.polymarketexchange.com:443 \ describe polymarket.v1.CreateMarketDataSubscriptionRequest
The -authority flag sets the :authority header for TLS certificate validation.
Generating Python Client Code After downloading the proto files, generate Python code:
# Extract protos unzip polymarket-v1-protos.zip -d protos/polymarket/v1/ # Generate Python code python -m grpc_tools.protoc \ --python_out=. \ --grpc_python_out=. \ --proto_path=protos \ protos/polymarket/v1/ * .proto
This generates:
*_pb2.py - Message and enum definitions*_pb2_grpc.py - Service stubs
Market Data Streaming MarketDataSubscriptionAPI Service service MarketDataSubscriptionAPI { rpc CreateMarketDataSubscription ( CreateMarketDataSubscriptionRequest ) returns ( stream CreateMarketDataSubscriptionResponse ); }
Python Usage from polymarket.v1 import marketdatasubscription_pb2 from polymarket.v1 import marketdatasubscription_pb2_grpc # Create request request = marketdatasubscription_pb2.CreateMarketDataSubscriptionRequest( symbols = [ "SYMBOL-123" ], depth = 10 ) # Use stub stub = marketdatasubscription_pb2_grpc.MarketDataSubscriptionAPIStub(channel) response_stream = stub.CreateMarketDataSubscription(request, metadata = metadata)
Request Fields Field Type Description symbolslist[str]Symbols to subscribe to. Empty = all symbols. unaggregatedboolIf true, receive raw orders. If false, aggregated book. depthintNumber of price levels. Default: 10 snapshot_onlyboolIf true, receive snapshot then close.
Response Fields if response.HasField( 'heartbeat' ): # Keep-alive message pass elif response.HasField( 'update' ): update = response.update print ( f "Symbol: { update.symbol } " ) print ( f "Bids: { len (update.bids) } " ) print ( f "Offers: { len (update.offers) } " )
Field Type Description symbolstrInstrument symbol bidslist[BookEntry]Bid side of order book offerslist[BookEntry]Offer/ask side of order book stateInstrumentStateCurrent instrument state (optional) statsInstrumentStatsMarket statistics
Instrument State Tracking: The state field is optional. Use ListInstruments to get and cache the initial state, then subscribe to the instrument state change subscription for real-time state updates.
Order Entry Streaming OrderEntryAPI Service service OrderEntryAPI { rpc CreateOrderSubscription ( CreateOrderSubscriptionRequest ) returns ( stream CreateOrderSubscriptionResponse ); rpc InsertOrder ( InsertOrderRequest ) returns ( InsertOrderResponse ); rpc CancelOrder ( CancelOrderRequest ) returns ( CancelOrderResponse ); }
Python Usage from polymarket.v1 import trading_pb2 from polymarket.v1 import trading_pb2_grpc # Create order subscription request request = trading_pb2.CreateOrderSubscriptionRequest( symbols = [ "SYMBOL-123" ], accounts = [], snapshot_only = False ) # Use stub stub = trading_pb2_grpc.OrderEntryAPIStub(channel) response_stream = stub.CreateOrderSubscription(request, metadata = metadata)
Subscription Request Fields Field Type Description symbolslist[str]Filter by symbols. Empty = all. accountslist[str]Filter by accounts. Empty = all user’s accounts. snapshot_onlyboolIf true, snapshot only.
Response Processing if response.HasField( 'heartbeat' ): pass elif response.HasField( 'snapshot' ): for order in response.snapshot.orders: print ( f "Order: { order.id } - { order.symbol } " ) elif response.HasField( 'update' ): for execution in response.update.executions: print ( f "Execution: { execution.id } " )
Enumerations Side Name Value SIDE_BUY1 SIDE_SELL2
OrderType Name Value ORDER_TYPE_MARKET_TO_LIMIT1 ORDER_TYPE_LIMIT2 ORDER_TYPE_STOP3 ORDER_TYPE_STOP_LIMIT4
TimeInForce Name Value Description TIME_IN_FORCE_DAY1 Expires end of day TIME_IN_FORCE_GTC2 Good-till-canceled TIME_IN_FORCE_IOC3 Immediate-or-cancel TIME_IN_FORCE_FOK4 Fill-or-kill TIME_IN_FORCE_GTT5 Good-till-time
OrderState Name Value Description ORDER_STATE_NEW1 Accepted and resting ORDER_STATE_PARTIALLY_FILLED2 Partially executed ORDER_STATE_FILLED3 Completely filled ORDER_STATE_CANCELED4 Canceled ORDER_STATE_REJECTED7 Rejected ORDER_STATE_EXPIRED9 Expired
ExecutionType Name Value Description EXECUTION_TYPE_NEW1 Order confirmation EXECUTION_TYPE_PARTIAL_FILL2 Partial fill EXECUTION_TYPE_FILL3 Complete fill EXECUTION_TYPE_CANCELED4 Cancellation EXECUTION_TYPE_REJECTED7 Rejection EXECUTION_TYPE_TRADE9 Trade execution EXECUTION_TYPE_EXPIRED10 Expiration
InstrumentState Primary State Flow Name Value Description INSTRUMENT_STATE_PENDING— Initial state for a newly created instrument which has not yet begun trading. Clients will receive a PENDING → OPEN state change notification but will not see PENDING in the order book. INSTRUMENT_STATE_OPEN1 In this state, the instrument is open for continuous order entry and matching. INSTRUMENT_STATE_CLOSED0 In this state, orders can not be entered, modified, or canceled, and no matching occurs. Any existing Day orders will be expired. INSTRUMENT_STATE_EXPIRED4 An instrument moves to this state when its Expiration Date/Time is reached. In this state, any resting orders are expired and no new orders can be entered. INSTRUMENT_STATE_TERMINATED5 When an instrument’s Termination Date is reached, the order book is removed from the matching engine, orders are canceled, and positions are closed. Historical data will still remain in Polymarket US ledgers.
Exception States Name Value Description INSTRUMENT_STATE_SUSPENDED3 Orders can be canceled but no matching occurs, and no order entry or modification is allowed. INSTRUMENT_STATE_HALTED6 This state is similar to SUSPENDED, with the exception that orders cannot be canceled.
Other Possible States Name Value Description INSTRUMENT_STATE_PREOPEN2 Orders can be entered and modified, but no matching occurs. When the instrument transitions to an OPEN state, the orders entered during PREOPEN will match at a single opening price that is automatically determined by an algorithm that is designed to maximize the volume traded at the open. INSTRUMENT_STATE_MATCH_AND_CLOSE_AUCTION7 This state is similar to PREOPEN, with the exception that matching will occur upon the transition of this state to any other state. This state is useful if you want matching to occur at the end of the state, but you don’t want the instrument to be open after.
Price Representation All prices are int64 values. Divide by the instrument’s price_scale to get the decimal value.decimal_price = order.price / order.price_scale print ( f "Price: $ { decimal_price :.4f} " )
Next Steps 
