User Data

Endpoints for querying your profile, orders, trades, positions, fiat sessions, notifications, referrals, and rebates. All endpoints require authentication.

Profile

GET /v1/user/profile

Returns the authenticated user's profile including wallet addresses, display name, and account settings.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "display_name": "trader1",
  "wallet_address": "0xabc...",
  "linked_wallets": ["0xabc...", "0xdef..."],
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

Orders (Enhanced)

GET /v1/user/orders/v2

Scope: read:account

Query your orders with advanced filters and pagination.

Query Parameters

Response

{
  "orders": [
    {
      "id": "...",
      "order_hash": "0x...",
      "market_id": "...",
      "side": "BUY",
      "price": "0.50000000",
      "status": "open",
      "remaining": "1000000",
      "filled_amount": "0",
      "time_in_force": "GTC",
      "post_only": false,
      "created_at": "2024-03-01T00:00:00Z"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Trades (Enhanced)

GET /v1/user/trades/v2

Scope: read:account

Query your trade history with filters.

Query Parameters

Response

{
  "trades": [
    {
      "id": "...",
      "market_id": "...",
      "taker_order_id": "...",
      "maker_order_id": "...",
      "price": "0.50000000",
      "amount": "1000000",
      "taker_side": "BUY",
      "outcome_index": 0,
      "matched_at": "2024-03-01T12:30:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Positions

GET /v1/user/positions

Returns all positions for the authenticated user across all markets.

Response

[
  {
    "id": "...",
    "market_id": "...",
    "outcome_index": 0,
    "quantity": "5000000",
    "average_entry_price": "0.45000000",
    "realized_pnl": "0",
    "claimed": false
  }
]

Redeemable Positions

GET /v1/user/redeemable

Returns positions in resolved markets that can be claimed (redeemed for USDC).

Response

[
  {
    "market_id": "...",
    "outcome_index": 0,
    "quantity": "5000000",
    "payout": "5000000",
    "resolution": "YES",
    "resolved_at": "2024-03-15T18:00:00Z"
  }
]

Claim Winnings

POST /v1/user/positions/:marketId/claim

Initiates an on-chain redemption of winning positions in a resolved market. This triggers a transaction on Polygon to transfer USDC to your wallet.

Response

{
  "message": "claim initiated",
  "market_id": "...",
  "tx_hash": "0x..."
}

Mark Position Claimed

POST /v1/user/positions/:marketId/mark-claimed

Marks a position as claimed after an external on-chain redemption (e.g., if you called the contract directly).

Response

{
  "message": "position marked as claimed"
}

Fiat Sessions

List Sessions

GET /v1/user/fiat/sessions

Returns all on-ramp and off-ramp sessions for the authenticated user.

Get Session

GET /v1/user/fiat/sessions/:id

Returns details of a specific fiat session.

Create On-Ramp Session

POST /v1/user/fiat/onramp/sessions

Creates a new fiat-to-crypto on-ramp session (deposit USDC).

Complete On-Ramp Session

POST /v1/user/fiat/onramp/sessions/:id/complete

Marks an on-ramp session as complete after payment confirmation.

Create Off-Ramp Session

POST /v1/user/fiat/offramp/sessions

Creates a new crypto-to-fiat off-ramp session (withdraw to bank).

Rebates

GET /v1/user/rebates

Returns trading rebate history and balances for the authenticated user.

Response

{
  "total_rebates": "15000000",
  "pending_rebates": "5000000",
  "credited_rebates": "10000000",
  "history": [
    {
      "id": "...",
      "amount": "5000000",
      "reason": "maker_rebate",
      "created_at": "2024-03-01T12:00:00Z"
    }
  ]
}

Referrals

Get Referral Info

GET /v1/user/referral

Returns the user's referral code and referral status.

Response

{
  "referral_code": "ABC123",
  "referrals_count": 5,
  "is_referred": true,
  "referred_by": "XYZ789"
}

Get Referral Earnings

GET /v1/user/referral/earnings

Returns earnings generated from referrals.

Redeem Referral Code

POST /v1/user/referral/redeem

Apply a referral code to your account.

Request Body

{
  "code": "ABC123"
}

Notifications

List Notifications

GET /v1/user/notifications

Returns notifications for the authenticated user (order fills, market resolutions, etc.).

Response

{
  "notifications": [
    {
      "id": "...",
      "type": "order_filled",
      "message": "Your BUY order was filled at 0.52",
      "read": false,
      "created_at": "2024-03-01T14:30:00Z"
    }
  ]
}

Mark Notification Read

POST /v1/user/notifications/:id/read

Marks a single notification as read.

Mark All Notifications Read

POST /v1/user/notifications/read-all

Marks all notifications as read.

Legacy Endpoints

The original order and trade endpoints are still available at:

• GET /v1/user/orders — Basic order list (no filters)
• GET /v1/user/trades — Basic trade list (no filters)

Use the /v2 versions for advanced filtering and pagination.