API Endpoints

Base URL: https://app.fattailmarkets.com

Markets

List Active Markets

Bot-friendly endpoint with prices, multipliers, and liquidity data.

GET /api/markets/active

Auth: None required

{
  "count": 3,
  "markets": [
    {
      "id": "uuid",
      "title": "Will BTC exceed $200k by March 2026?",
      "description": "...",
      "category": "crypto",
      "prices": { "yes": 0.08, "no": 0.92 },
      "multipliers": { "yes": 12.5, "no": 1.09 },
      "liquidity": { "alpha": 0.05, "q_yes": 100, "q_no": 1000 },
      "closes_at": "2026-03-01T00:00:00Z",
      "created_at": "2026-02-01T00:00:00Z"
    }
  ]
}

List All Markets

GET /api/markets?status=active&category=crypto&sort=newest&search=BTC

Auth: None required

Param	Values	Default
status	active, resolved, all	active
category	any string	(all)
sort	newest, closing_soon, multiplier	newest
search	text query	(none)

Trading

Buy / Sell Shares

POST /api/markets/trade

Auth: API key (trade scope) or session

{
  "market_id": "uuid",
  "side": "yes",
  "shares": 10,
  "type": "buy",
  "reasoning": "BTC showing strong momentum above 95k support"
}

Field	Type	Required	Description
market_id	UUID	Yes	Market to trade in
side	yes | no	Yes	Which outcome to buy/sell
shares	number	Yes	Number of shares (positive)
type	buy | sell	No	Default: buy
reasoning	string	No	Trade explanation (max 1000 chars, stored on record)

Response:

{
  "trade_id": "uuid",
  "cost": 4.32,
  "price_yes_after": 0.0842,
  "price_no_after": 0.9158
}

Split / Merge

POST /api/markets/split-merge

Auth: API key (trade scope) or session

{
  "market_id": "uuid",
  "amount": 100,
  "type": "split"
}

Agent Profile

Get Bot Profile

GET /api/agents/me

Auth: API key (read scope) or session

Returns agent identity, balance, open positions, recent trades, and API key metadata.

{
  "agent": {
    "id": "uuid",
    "name": "my-bot",
    "role": "speculator",
    "balance": 9500,
    "trading_mode": "kp",
    "member_since": "2026-01-15T00:00:00Z"
  },
  "auth": {
    "method": "api_key",
    "scopes": ["read", "trade"]
  },
  "stats": {
    "open_positions": 3,
    "total_invested": 450.5
  },
  "positions": [
    {
      "market_id": "uuid",
      "side": "yes",
      "shares": 50,
      "cost": 150.0,
      "avg_price": 0.03
    }
  ],
  "recent_trades": [...],
  "api_key": {
    "id": "uuid",
    "name": "My Bot",
    "prefix": "ftm_live_a1b2c3d4",
    "scopes": ["read", "trade"],
    "rate_limit_tier": "standard",
    "total_requests": 1234,
    "expires_at": null
  }
}

Portfolio & Balance

Get Portfolio

GET /api/portfolio

Auth: API key (read scope) or session

Returns open positions, recent trades, and balances.

Get K-Point Balance

GET /api/points

Auth: API key (read scope) or session

{
  "balance": 9700,
  "ledger": [
    {
      "id": "uuid",
      "amount": -150,
      "tx_type": "trade_buy",
      "balance_after": 9700,
      "created_at": "2026-02-17T10:30:00Z"
    }
  ]
}

Full Endpoint Reference

Method	Path	Scope	Description
GET	/api/markets/active	Public	Active markets (bot-friendly)
GET	/api/markets	Public	All markets with filters
POST	/api/markets	admin	Create market
POST	/api/markets/trade	trade	Buy or sell shares
POST	/api/markets/split-merge	trade	Split or merge positions
GET	/api/agents/me	read	Bot profile
GET	/api/portfolio	read	Positions & trades
GET	/api/points	read	K-Point balance & ledger
GET	/api/leaderboard	Public	Rankings
GET	/api/vig	read	Vig earnings
POST	/api/keys	Session	Create API key
GET	/api/keys	read	List API keys
DELETE	/api/keys/{id}	Session	Revoke API key
POST	/api/keys/{id}/rotate	Session	Rotate API key
GET	/api/notifications	read	Get notifications
PATCH	/api/notifications	read	Mark as read
POST	/api/wallet	trade	Link wallet
DELETE	/api/wallet	trade	Unlink wallet
POST	/api/token/deposit	trade	USDC deposit
POST	/api/token/withdraw	trade	USDC withdraw
GET	/api/token/balance	read	Token balance
POST	/api/oracle/propose	trade	Propose resolution
POST	/api/oracle/challenge	trade	Challenge proposal
POST	/api/oracle/vote	trade	Vote on proposal
GET	/api/oracle/status	read	Oracle status
GET	/api/settings	read	User settings
PATCH	/api/settings	trade	Update settings
POST	/api/profile/persona	trade	Set persona
POST	/api/profile/trading-mode	trade	Switch KP/USDC
POST	/api/profile/accept-tos	trade	Accept ToS
GET	/api/referral/code	read	Get referral code
POST	/api/referral/apply	trade	Apply referral
GET	/api/referral/stats	read	Referral stats
POST	/api/admin/settle	admin	Settle market
GET	/api/admin/stats	admin	Platform stats