Protocol Buffer Reference - Polymarket US Documentation

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.MarketDataSubscriptionAPI`	Real-time market data streaming
`polymarket.v1.OrderEntryAPI`	Order submission and streaming
`polymarket.v1.ComboAPI`	Combo instrument creation and exact-symbol reads (beta)
`polymarket.v1.RFQAPI`	Combo RFQs, quotes, and RFQ event streaming (beta)
`polymarket.v1.OrderAPI`	Order search and history
`polymarket.v1.PositionAPI`	Position and balance queries
`polymarket.v1.AccountsAPI`	Account information
`polymarket.v1.MarketDataAPI`	Instrument and symbol data
`polymarket.v1.DropCopyAPI`	Execution feed
`polymarket.v1.KYCAPI`	KYC verification
`polymarket.v1.AeropayAPI`	ACH payments
`polymarket.v1.CheckoutAPI`	Card payments
`polymarket.v1.FundingAPI`	Funding management
`polymarket.v1.HealthAPI`	Health check

Obtaining Proto Files

Download Proto Files

Get the complete Protocol Buffer definitions to generate client libraries in any language

Use the downloaded definitions as the client contract. Do not make client startup depend on gRPC reflection, whose availability can differ by environment.

Generating Python Client Code

After downloading the proto files, generate Python code:

unzip polymarket-protos.zip -d protos
python -m grpc_tools.protoc --python_out=. --grpc_python_out=. --proto_path=protos/api protos/api/polymarket/v1/*.proto protos/api/google/api/*.proto protos/api/protoc-gen-openapiv2/options/*.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
`symbols`	`list[str]`	Symbols to subscribe to. Empty = all symbols.
`unaggregated`	`bool`	If true, receive raw orders. If false, aggregated book.
`depth`	`int`	Number of price levels. Default: 10
`snapshot_only`	`bool`	If 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
`symbol`	`str`	Instrument symbol
`bids`	`list[BookEntry]`	Bid side of order book
`offers`	`list[BookEntry]`	Offer/ask side of order book
`state`	`InstrumentState`	Current instrument state (optional)
`stats`	`InstrumentStats`	Market 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
`symbols`	`list[str]`	Filter by symbols. Empty = all.
`accounts`	`list[str]`	Filter by accounts. Empty = all user’s accounts.
`snapshot_only`	`bool`	If 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}")

RFQ Events Streaming

Upcoming - beta access required. RFQ events are part of the upcoming RFQ API beta. Reach out to institutional@polymarket.us to join the beta test.

ComboAPI and RFQAPI Services

service ComboAPI {
    rpc CreateCombo(CreateComboRequest) returns (CreateComboResponse);
    rpc GetCombos(GetCombosRequest) returns (GetCombosResponse);
}

service RFQAPI {
    rpc GetRFQUserID(GetRFQUserIDRequest) returns (GetRFQUserIDResponse);
    rpc GetRFQs(GetRFQsRequest) returns (GetRFQsResponse);
    rpc CreateRFQ(CreateRFQRequest) returns (CreateRFQResponse);
    rpc DeleteRFQ(DeleteRFQRequest) returns (DeleteRFQResponse);
    rpc GetQuotes(GetQuotesRequest) returns (GetQuotesResponse);
    rpc CreateQuote(CreateQuoteRequest) returns (CreateQuoteResponse);
    rpc DeleteQuote(DeleteQuoteRequest) returns (DeleteQuoteResponse);
    rpc AcceptQuote(AcceptQuoteRequest) returns (AcceptQuoteResponse);
    rpc ConfirmQuote(ConfirmQuoteRequest) returns (ConfirmQuoteResponse);
    rpc StreamRFQEvents(StreamRFQEventsRequest)
        returns (stream StreamRFQEventsResponse);
}

Request Fields

StreamRFQEventsRequest is currently empty.

Response Events

Each StreamRFQEventsResponse has one event payload:

Event	Description
`rfq_created`	A new combo RFQ was created.
`rfq_closed`	An RFQ closed through deletion or quote acceptance.
`quote_created`	A quote was created.
`quote_deleted`	A quote was deleted.
`quote_accepted`	One quote side was accepted and last look started.
`quote_confirmed`	The maker confirmed and paired order submission was scheduled.
`quote_executed`	Both exchange orders were accepted for submission.

For request/response field detail and a Python example, see RFQ Events Streaming.

Funding Streaming

FundingAPI Service

service FundingAPI {
    rpc CreateFundingTransactionSubscription(CreateFundingTransactionSubscriptionRequest)
        returns (stream CreateFundingTransactionSubscriptionResponse);

    rpc CreateBalanceLedgerSubscription(CreateBalanceLedgerSubscriptionRequest)
        returns (stream CreateBalanceLedgerSubscriptionResponse);
}

RPC	Description	Required Scope
`CreateFundingTransactionSubscription`	Real-time deposit / withdrawal state changes	`read:funding`
`CreateBalanceLedgerSubscription`	Real-time balance ledger entries with `resume_time` replay	`read:positions`

CreateBalanceLedgerSubscriptionRequest

Field	Type	Description
`account`	`str`	Required. Fully qualified account name.
`currency`	`str`	Optional. ISO currency code (e.g., `USD`).
`entry_types`	`list[LedgerEntryType]`	Optional. Filter by allowlisted entry types.
`resume_time`	`Timestamp`	Optional. Replay entries with `update_time >= resume_time`. Clamped to `2026-05-01T00:00:00Z`.

For full request/response field detail and a Python example, see Balance Ledger Streaming.

Enumerations

Side

Name	Value
`SIDE_BUY`	1
`SIDE_SELL`	2

OrderType

Name	Value
`ORDER_TYPE_MARKET_TO_LIMIT`	1
`ORDER_TYPE_LIMIT`	2
`ORDER_TYPE_STOP`	3
`ORDER_TYPE_STOP_LIMIT`	4

TimeInForce

Name	Value	Description
`TIME_IN_FORCE_DAY`	1	Expires end of day
`TIME_IN_FORCE_GTC`	2	Good-till-canceled
`TIME_IN_FORCE_IOC`	3	Immediate-or-cancel
`TIME_IN_FORCE_FOK`	4	Fill-or-kill
`TIME_IN_FORCE_GTT`	5	Good-till-time

OrderState

Name	Value	Description
`ORDER_STATE_NEW`	1	Accepted and resting
`ORDER_STATE_PARTIALLY_FILLED`	2	Partially executed
`ORDER_STATE_FILLED`	3	Completely filled
`ORDER_STATE_CANCELED`	4	Canceled
`ORDER_STATE_REJECTED`	7	Rejected
`ORDER_STATE_EXPIRED`	9	Expired

ExecutionType

Name	Value	Description
`EXECUTION_TYPE_NEW`	1	Order confirmation
`EXECUTION_TYPE_PARTIAL_FILL`	2	Partial fill
`EXECUTION_TYPE_FILL`	3	Complete fill
`EXECUTION_TYPE_CANCELED`	4	Cancellation
`EXECUTION_TYPE_REJECTED`	7	Rejection
`EXECUTION_TYPE_TRADE`	9	Trade execution
`EXECUTION_TYPE_EXPIRED`	10	Expiration

InstrumentState

Primary State Flow

Name	Value	Description
`INSTRUMENT_STATE_PENDING`	8	Initial state for a newly created instrument which has not yet begun trading.
`INSTRUMENT_STATE_OPEN`	1	In this state, the instrument is open for continuous order entry and matching.
`INSTRUMENT_STATE_CLOSED`	0	In this state, orders can not be entered, modified, or canceled, and no matching occurs. Any existing Day orders will be expired.
`INSTRUMENT_STATE_EXPIRED`	4	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_TERMINATED`	5	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_SUSPENDED`	3	Orders can be canceled but no matching occurs, and no order entry or modification is allowed.
`INSTRUMENT_STATE_HALTED`	6	This state is similar to SUSPENDED, with the exception that orders cannot be canceled.

Other Possible States

Name	Value	Description
`INSTRUMENT_STATE_PREOPEN`	2	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_AUCTION`	7	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.

LedgerEntryType

Used by CreateBalanceLedgerSubscription and the Balance Ledger REST endpoints. Only the allowed values are returned to clients; suppressed values are filtered server-side.

Allowed

Name	Value	Description
`DEPOSIT`	1	Funds deposited
`WITHDRAWAL`	2	Funds withdrawn
`ORDER_EXECUTION`	3	Cash impact of a trade execution
`CORRECTION`	4	Manual correction
`RESOLUTION`	6	Market resolution / settlement payout
`MANUAL_ADJUSTMENT`	7	Admin adjustment
`ACCOUNT_PROPERTY_ADJUSTMENT`	10	Account property change
`COMMISSION`	11	Trading fee
`WITHDRAWAL_REJECTION`	16	Failed withdrawal returned to balance
`MANUAL_TRANSFER`	17	Internal transfer
`PENDING_WITHDRAWAL_CREATION`	22	Withdrawal initiated (funds reserved)

Suppressed (internal — never returned to clients)

Name	Value
`NETTING`	5
`SECURITY_BALANCE_ADJUSTMENT`	8
`SECURITY_MARK_TO_MARKET`	9
`CONTRACT_EXPIRATION`	12
`PENDING_CREDIT_ADJUSTMENT`	13
`BEGINNING_OF_DAY`	14
`SECURITY_WITHDRAWAL`	15
`AVERAGE_PRICE_TRANSFER`	18
`GIVE_UP`	19
`SYNCHRONIZATION`	20
`INTEREST`	21
`SETTLEMENT_FEE`	23

Requesting a suppressed value in entry_types returns Aborted (HTTP 409).

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

Market Data Stream

Learn about market data streaming

Order Stream

Learn about order streaming

Error Handling

Handle errors and reconnections

​Available Services

​Obtaining Proto Files

Download Proto Files

​Generating Python Client Code

​Market Data Streaming

​MarketDataSubscriptionAPI Service

​Python Usage

​Request Fields

​Response Fields

​Order Entry Streaming

​OrderEntryAPI Service

​Python Usage

​Subscription Request Fields

​Response Processing

​RFQ Events Streaming

​ComboAPI and RFQAPI Services

​Request Fields

​Response Events

​Funding Streaming

​FundingAPI Service

​CreateBalanceLedgerSubscriptionRequest

​Enumerations

​Side

​OrderType

​TimeInForce

​OrderState

​ExecutionType

​InstrumentState

​Primary State Flow

​Exception States

​Other Possible States

​LedgerEntryType

​Allowed

​Suppressed (internal — never returned to clients)

​Price Representation

​Next Steps

Market Data Stream

Order Stream

Error Handling

Available Services

Obtaining Proto Files

Generating Python Client Code

Market Data Streaming

MarketDataSubscriptionAPI Service

Python Usage

Request Fields

Response Fields

Order Entry Streaming

OrderEntryAPI Service

Python Usage

Subscription Request Fields

Response Processing

RFQ Events Streaming

ComboAPI and RFQAPI Services

Request Fields

Response Events

Funding Streaming

FundingAPI Service

CreateBalanceLedgerSubscriptionRequest

Enumerations

Side

OrderType

TimeInForce

OrderState

ExecutionType

InstrumentState

Primary State Flow

Exception States

Other Possible States

LedgerEntryType

Allowed

Suppressed (internal — never returned to clients)

Price Representation

Next Steps