Matcher API

The Matcher is an internal CLOB (Central Limit Order Book) engine. It handles order intake, price-time matching, and on-chain settlement. The backend calls the matcher — the frontend should not call it directly.

Base URL: https://clob-production.up.railway.app

Internal Service

The matcher is designed to be called by the backend only. Do not expose it to the public internet without proper access controls.

Endpoints

system

Health and stats

Operations

GET/healthGET/stats

---

Health check

GET

/health

Responses

Default Response

Content-Type

application/json

{

  

"ok": true

}

GET

/health

Playground

Samples

---

Matcher stats

GET

/stats

Responses

Default Response

Content-Type

application/json

{

  

"openOrders": 0

}

GET

/stats

Playground

Samples

---

markets

Market and token-pair registration

Operations

POST/markets/token-pairsGET/marketsGET/markets/{conditionId}DELETE/markets/{conditionId}

---

Register a token pair in backend storage

POST

/markets/token-pairs

Request Body

application/json

{

  

"tokenId": "string",

  

"complementTokenId": "string",

  

"conditionId": "string",

  

"question": "string",

  

"questionId": "string",

  

"outcomeSlotCount": 0

}

Responses

Default Response

Content-Type

application/json

{

  

"ok": true

}

POST

/markets/token-pairs

Playground

Server

Body

Samples

---

List markets with token pairs

GET

/markets

Responses

Default Response

Content-Type

application/json

{

  

"markets": [

  

  

{

  

  

  

"conditionId": "string",

  

  

  

"question": "string",

  

  

  

"questionId": "string",

  

  

  

"outcomeSlotCount": 0,

  

  

  

"tokenPairs": [

  

  

  

  

{

  

  

  

  

  

"tokenId": "string",

  

  

  

  

  

"complementTokenId": "string",

  

  

  

  

  

"conditionId": "string"

  

  

  

  

}

  

  

  

]

  

  

}

  

]

}

GET

/markets

Playground

Samples

---

Get a market by condition id

GET

/markets/{conditionId}

Parameters

Path Parameters

conditionId*

Type

string

Required

Responses

Default Response

Content-Type

application/json

{

  

"market": {

  

  

"conditionId": "string",

  

  

"question": "string",

  

  

"questionId": "string",

  

  

"outcomeSlotCount": 0,

  

  

"tokenPairs": [

  

  

  

{

  

  

  

  

"tokenId": "string",

  

  

  

  

"complementTokenId": "string",

  

  

  

  

"conditionId": "string"

  

  

  

}

  

  

]

  

}

}

GET

/markets/{conditionId}

Playground

Server

Variables

Key

Value

conditionId*

Samples

---

Delete a market and all related data by condition id

DELETE

/markets/{conditionId}

Parameters

Path Parameters

conditionId*

Type

string

Required

Responses

Default Response

Content-Type

application/json

{

  

"ok": true

}

DELETE

/markets/{conditionId}

Playground

Server

Variables

Key

Value

conditionId*

Samples

---

orders

Order intake and orderbook queries

Operations

GET/ordersPOST/ordersPOST/orders/cancelGET/orders/{hash}GET/orderbook/{tokenId}

---

List recent orders

GET

/orders

Parameters

Query Parameters

account

Type

string

conditionId

Type

string

limit

Responses

Default Response

Content-Type

application/json

{

  

"orders": [

  

  

{

  

  

  

"orderHash": "string",

  

  

  

"tokenId": "string",

  

  

  

"maker": "string",

  

  

  

"signer": "string",

  

  

  

"taker": "string",

  

  

  

"side": 0,

  

  

  

"signatureType": 0,

  

  

  

"makerAmount": "string",

  

  

  

"takerAmount": "string",

  

  

  

"remainingMakerAmount": "string",

  

  

  

"expiration": "string",

  

  

  

"nonce": "string",

  

  

  

"feeRateBps": "string",

  

  

  

"salt": "string",

  

  

  

"signature": "string",

  

  

  

"status": "string",

  

  

  

"conditionId": "string",

  

  

  

"price": "string",

  

  

  

"lastSettlementTxHash": "string",

  

  

  

"createdAt": "string",

  

  

  

"updatedAt": "string"

  

  

}

  

]

}

GET

/orders

Playground

Server

Variables

Key

Value

account

conditionId

limit

Samples

---

Submit a signed order

POST

/orders

Request Body

application/json

{

  

"conditionId": "string",

  

"order": {

  

  

"salt": "string",

  

  

"maker": "string",

  

  

"signer": "string",

  

  

"taker": "string",

  

  

"tokenId": "string",

  

  

"makerAmount": "string",

  

  

"takerAmount": "string",

  

  

"expiration": "string",

  

  

"nonce": "string",

  

  

"feeRateBps": "string",

  

  

"side": "string",

  

  

"signatureType": "string",

  

  

"signature": "string"

  

}

}

Responses

Default Response

Content-Type

application/json

{

  

"orderHash": "string",

  

"status": "string",

  

"match": {

  

  

"matchId": 0,

  

  

"makerOrderHash": "string"

  

}

}

POST

/orders

Playground

Server

Body

Samples

---

Mark an order as locally cancelled

POST

/orders/cancel

Request Body

application/json

{

  

"orderHash": "string"

}

Responses

Default Response

Content-Type

application/json

{

  

"ok": true

}

POST

/orders/cancel

Playground

Server

Body

Samples

---

Get order and event history

GET

/orders/{hash}

Parameters

Path Parameters

hash*

Type

string

Required

Responses

Default Response

Content-Type

application/json

{

  

"error": null

}

GET

/orders/{hash}

Playground

Server

Variables

Key

Value

hash*

Samples

---

Get orderbook by token id

GET

/orderbook/{tokenId}

Parameters

Path Parameters

tokenId*

Required

Responses

Default Response

Content-Type

application/json

{

  

"error": null

}

GET

/orderbook/{tokenId}

Playground

Server

Variables

Key

Value

tokenId*

Samples

---