Backend API

The Backend is the primary API surface for the frontend application. It provides endpoints for authentication, market management, trading, user profiles, and file uploads.

Base URL: https://backend-production-ef0b.up.railway.app

Authentication

Mechanism	Header	Purpose
API Key	x-api-key: YOUR_KEY	Required on most endpoints
JWT Bearer	Authorization: Bearer TOKEN	Required for authenticated user actions

# Example: list all markets
curl -H "x-api-key: 019cccd3-bfc1-7503-ab84-25907019f053" \
  https://backend-production-ef0b.up.railway.app/markets

Endpoints

System

Operations

GET/health

---

System health check

GET

/health

Authorizations

api-key

Type

API Key (header: x-api-key)

Responses

GET

/health

Playground

Server

Authorization

api-key

Samples

---

Users

Operations

POST/users/authGET/users/{id}PATCH/users/{id}GET/users/check-username/{username}

---

Create or update user after signature verification (Internal usage)

POST

/users/auth

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Request Body

application/json

{

  

"id": "string",

  

"username": "string",

  

"avatarUrl": "string",

  

"role": {

  

}

}

Responses

POST

/users/auth

Playground

Server

Authorization

bearer

Body

Samples

---

Retrieve a user profile by wallet address

GET

/users/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

GET

/users/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Update your own user profile

PATCH

/users/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Request Body

application/json

{

  

"username": "string",

  

"avatarUrl": "string"

}

Responses

PATCH

/users/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Body

Samples

---

Check if a username is currently available

GET

/users/check-username/{username}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

username*

Type

string

Required

Responses

GET

/users/check-username/{username}

Playground

Server

Authorization

bearer

Variables

Key

Value

username*

Samples

---

Markets

Operations

GET/marketsPOST/marketsGET/markets/{id}DELETE/markets/{id}PATCH/markets/{id}GET/markets/{id}/tradingGET/markets/{id}/orderbookPOST/markets/{id}/orders

---

Retrieve all markets

GET

/markets

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Responses

Content-Type

application/json

[

  

{

  

}

]

GET

/markets

Playground

Server

Authorization

bearer

Samples

---

Create a new canonical app market and register it with the matcher when trading ids are present

POST

/markets

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Request Body

application/json

{

  

"question": "string",

  

"description": "string",

  

"image": "string",

  

"category": "string",

  

"endTimestamp": "string",

  

"resolutionSource": "string",

  

"conditionId": "string",

  

"questionId": "string",

  

"yesTokenId": "string",

  

"noTokenId": "string",

  

"outcomes": [

  

  

{

  

  

  

"name": "string",

  

  

  

"image": "string",

  

  

  

"sortOrder": 0,

  

  

  

"indexSet": "string",

  

  

  

"tokenId": "string",

  

  

  

"complementIndexSet": "string",

  

  

  

"complementTokenId": "string"

  

  

}

  

],

  

"outcomeSlotCount": 0

}

Responses

Content-Type

application/json

{

}

POST

/markets

Playground

Server

Authorization

bearer

Body

Samples

---

Retrieve a single market by ID

GET

/markets/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

Content-Type

application/json

{

}

GET

/markets/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Permanently delete a market and all related data (Admin only)

DELETE

/markets/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

DELETE

/markets/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Update a market (Admin only)

PATCH

/markets/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Request Body

application/json

{

  

"status": {

  

},

  

"winningOutcomeId": "string",

  

"resolvedAt": "string"

}

Responses

Content-Type

application/json

{

}

PATCH

/markets/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Body

Samples

---

Retrieve a market trading snapshot

GET

/markets/{id}/trading

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

GET

/markets/{id}/trading

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Retrieve both YES and NO orderbooks for a market

GET

/markets/{id}/orderbook

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

GET

/markets/{id}/orderbook

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Submit a signed order for a market

POST

/markets/{id}/orders

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

Content-Type

application/json

{

}

POST

/markets/{id}/orders

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Trading

Operations

POST/orders/{hash}/cancelGET/me/orders

---

Cancel a matcher order by hash

POST

/orders/{hash}/cancel

Authorizations

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

hash*

Type

string

Required

Responses

POST

/orders/{hash}/cancel

Playground

Server

Authorization

api-key

Variables

Key

Value

hash*

Samples

---

List recent orders for an account

GET

/me/orders

Authorizations

api-key

Type

API Key (header: x-api-key)

Parameters

Query Parameters

account*

Type

string

Required

Responses

Content-Type

application/json

{

}

GET

/me/orders

Playground

Server

Authorization

api-key

Variables

Key

Value

account*

Samples

---

Uploads

Operations

POST/uploads/market-image

---

Upload a market image to Google Cloud Storage

POST

/uploads/market-image

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Request Body

multipart/form-data

object

Format"binary"

Responses

POST

/uploads/market-image

Playground

Server

Authorization

bearer

Body

Samples

---

Comments

Operations

POST/commentsGET/comments/market/{marketId}GET/comments/{id}DELETE/comments/{id}PATCH/comments/{id}POST/comments/{id}/like

---

Create a new comment

POST

/comments

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Request Body

application/json

{

  

"content": "string",

  

"marketId": "string",

  

"authorId": "string",

  

"parentId": "string"

}

Responses

Content-Type

application/json

{

}

POST

/comments

Playground

Server

Authorization

bearer

Body

Samples

---

Find all comments for a specific market

GET

/comments/market/{marketId}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

marketId*

Type

string

Required

Responses

Content-Type

application/json

[

  

{

  

}

]

GET

/comments/market/{marketId}

Playground

Server

Authorization

bearer

Variables

Key

Value

marketId*

Samples

---

Retrieve a single comment by ID

GET

/comments/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

Content-Type

application/json

{

}

GET

/comments/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Remove a comment (Author or Admin only)

DELETE

/comments/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

DELETE

/comments/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Update a comment (Author only)

PATCH

/comments/{id}

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Request Body

application/json

{

  

"content": "string"

}

Responses

PATCH

/comments/{id}

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Body

Samples

---

Like a comment

POST

/comments/{id}/like

Authorizations

bearer

Type

HTTP (bearer)

or

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

Responses

POST

/comments/{id}/like

Playground

Server

Authorization

bearer

Variables

Key

Value

id*

Samples

---

Auth

Operations

GET/auth/nonce/{address}POST/auth/verifyPOST/auth/refresh

---

Generate a SIWE nonce for a wallet address

GET

/auth/nonce/{address}

Authorizations

api-key

Type

API Key (header: x-api-key)

Parameters

Path Parameters

address*

Type

string

Required

Responses

GET

/auth/nonce/{address}

Playground

Server

Authorization

api-key

Variables

Key

Value

address*

Samples

---

Verify SIWE signature and return JWT tokens

POST

/auth/verify

Authorizations

api-key

Type

API Key (header: x-api-key)

Request Body

application/json

{

  

"message": "string",

  

"signature": "string"

}

Responses

POST

/auth/verify

Playground

Server

Authorization

api-key

Body

Samples

---

Refresh access token using a refresh token

POST

/auth/refresh

Authorizations

api-key

Type

API Key (header: x-api-key)

Request Body

application/json

{

  

"refreshToken": "string"

}

Responses

POST

/auth/refresh

Playground

Server

Authorization

api-key

Body

Samples

---