WebSocket Real-Time Events

Overview

WebSocket provides real-time TPX event notifications with sub-second latency. Use alongside webhooks for instant event delivery while maintaining webhook reliability as a backup.

Endpoint

Production:

wss://platform-api.tradepost.co/ws

Quick Start

1. Connect to WebSocket endpoint
2. Authenticate with your API key
3. Subscribe to rooms
4. Receive real-time events

Message Format

All messages follow the same structure:

{
  "msg_type": "string",
  "payload": { }
}

Server responses also include a sent_at timestamp (epoch ms). Clients do not need to send sent_at.

Authentication

Send your API key after connecting:

{
  "msg_type": "authenticate",
  "payload": {
    "token": "tp_live_your_api_key_here"
  }
}

Response:

{
  "msg_type": "authenticated",
  "sent_at": 1704067200000,
  "payload": {
    "account_id": "1fdf89c2-75e9-495d-aa38-076c90a640c1",
    "auth_method": "api_key"
  }
}

Available Rooms

Subscribe to specific event types or use ALL for all events:

Room Name	Description
BID_REQUEST	New auction started
BID_OUTBID	Your bid was outbid
AUCTION_RESULT	Auction concluded
CONDITIONAL_BID_APPLIED	Auto-bid triggered
CONDITIONAL_BID_STATUS_CHANGE	Conditional bid status changed
CONDITIONAL_BID_EXPIRING_SOON	Conditional bid approaching expiration
INSTANT_CASH_OFFER_STATUS_CHANGE	Offer status changed
TRANSFER_CONFIRMATION_RECEIVED	Items received from seller
PAYMENT_CHARGED	Payment charged
PAYMENT_FAILED	Payment failed
PAYMENT_SETTLED	Payment settled
ALL	All TPX events

Subscribing to Events

{
  "msg_type": "subscribe",
  "payload": {
    "rooms": ["BID_REQUEST", "AUCTION_RESULT"]
  }
}

Response:

{
  "msg_type": "subscribed",
  "sent_at": 1704067200000,
  "payload": {
    "rooms": ["BID_REQUEST", "AUCTION_RESULT"]
  }
}

Receiving Events

Events arrive in real-time with the same payload structure as webhook messages.

BID_REQUEST Example

{
  "msg_type": "BID_REQUEST",
  "sent_at": 1704067200000,
  "payload": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "asset_type": "TICKET",
    "external_ids": {
      "SEATGEEK": "17346315",
      "TICKETMASTER": "vvG1YZ4bJalaRJ"
    },
    "asset_details": {
      "id": "3b9a0f8e-b6c8-4f79-89a5-2ed522bf9740",
      "event_name": "Taylor Swift - The Eras Tour",
      "venue_name": "MetLife Stadium",
      "event_date_utc": "2025-06-15T19:30:00Z",
      "event_date_local": "2025-06-15T15:30:00"
    },
    "config_details": {
      "id": "741335d5-c78c-414c-9f46-5b3577beea5f",
      "event_type": "PRIMARY"
    },
    "item_details": {
      "key_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "key_ids": ["a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"],
      "fair_values": [],
      "section": "Floor 2",
      "row": "12",
      "seat_numbers": ["1", "2"],
      "quantity": 2,
      "ticket_type": "MOBILE"
    }
  }
}

Keepalive

Server sends ping every 30 seconds. Respond with pong to maintain connection:

{
  "msg_type": "pong"
}

Error Handling

{
  "msg_type": "error",
  "sent_at": 1704067200000,
  "payload": {
    "error": "Invalid API key",
    "code": "AUTH_INVALID_API_KEY"
  }
}

Code	Description
AUTH_INVALID_API_KEY	Invalid API key
AUTH_API_KEY_INACTIVE	API key is inactive
AUTH_API_KEY_EXPIRED	API key has expired
AUTH_REQUIRED	Authentication required before subscription
NO_VALID_ROOMS	Room not accessible
INVALID_ROOM	Room does not exist
INVALID_MESSAGE	Malformed message
INVALID_JSON	JSON parsing failed

Best Practices

• Implement reconnection with exponential backoff (start at 1s, max 60s)
• Respond to pings within 30 seconds to prevent timeout
• Maintain webhook delivery as backup for guaranteed delivery
• Deduplicate events using conversation_id if receiving both WebSocket and webhook