Trading

The Trading API enables programmatic access to Vaulto's weighted position trading system. Trade LONG and SHORT positions on IPO valuation events with configurable floor payoffs.

Authentication

Trading endpoints have different authentication requirements:

Public Endpoints (No Auth Required)

These endpoints are publicly accessible and don't require any headers:

GET /api/trading/events — List supported events
GET /api/trading/valuation — Get pricing for an event
GET /api/trading/valuation/all — Get pricing for all events

Protected Endpoints (Auth Required)

All other endpoints require two headers:

Header	Description
`x-api-key`	Your API key from the dashboard
`x-user-id`	Your user ID (wallet address or account ID)

Example request:

bash

curl https://api.vaulto.ai/api/trading/settings \
  -H "x-api-key: vaulto_abc123..." \
  -H "x-user-id: 0x1234...5678"

Protected endpoints include:

Settings & credentials (/api/trading/settings, /api/trading/credentials)
Trading operations (/api/trading/buy, /api/trading/sell)
Position management (/api/trading/positions/*)
Order management (/api/trading/orders/*)
Trade history (/api/trading/history)

Overview

Vaulto trading uses prediction market bands to provide synthetic exposure to pre-IPO companies. Each position spans multiple valuation bands, weighted by probability. The floor payoff system (floorL/floorS) determines your downside protection.

Key Concepts

LONG position: Profits if IPO valuation exceeds expectations
SHORT position: Profits if IPO valuation falls below expectations
Floor payoff: Minimum percentage return even in worst-case scenario
Weighted exposure: Position distributed across bands based on probabilities

Supported Events

Currently supported IPO prediction markets (17 total):

SpaceX (Higher & Lower strikes)
OpenAI
Discord
Anthropic
Databricks
Fannie Mae
Stripe
Freddie Mac
Kraken
Clear Street Group
Liftoff Mobile
Consensys
Ledger
Perplexity
Strava

Use GET /api/trading/events to see the full list with band structures.

Settings & Credentials

Get Trading Settings Auth Required

GET /api/trading/settings

Retrieve current trading configuration.

Field	Type	Description
`floorL`	number	Floor payoff for LONG positions (0-1)
`floorS`	number	Floor payoff for SHORT positions (0-1)
`walletAddress`	string	Connected wallet address
`hasCredentials`	boolean	Whether Polymarket credentials are configured

Response:

json

{
  "floorL": 0.2,
  "floorS": 0.2,
  "walletAddress": "0x1234...5678",
  "hasCredentials": true
}

Try it — Get Settings

Set your API key in the nav bar to try this endpoint.

Update Trading Settings Auth Required

PUT /api/trading/settings

Update floor payoff configuration.

Parameter	Type	Required	Description
`floorL`	number	No	Floor payoff for LONG positions (0-1)
`floorS`	number	No	Floor payoff for SHORT positions (0-1)

Request:

json

{
  "floorL": 0.25,
  "floorS": 0.15
}

Try it — Update Settings

Set your API key in the nav bar to try this endpoint.

Set Polymarket Credentials Auth Required

POST /api/trading/credentials

Store encrypted Polymarket API credentials.

Parameter	Type	Required	Description
`apiKey`	string	Yes	Polymarket API key
`secret`	string	Yes	Polymarket API secret
`passphrase`	string	Yes	Polymarket API passphrase

Response:

json

{
  "success": true,
  "message": "Credentials stored successfully"
}

Try it — Set Credentials

Set your API key in the nav bar to try this endpoint.

Delete Polymarket Credentials Auth Required

DELETE /api/trading/credentials

Remove stored Polymarket credentials.

Response:

json

{
  "success": true,
  "message": "Credentials deleted"
}

Try it — Delete Credentials

Set your API key in the nav bar to try this endpoint.

Market Data

List Supported Events Public

GET /api/trading/events

Get all supported IPO events with their valuation bands.

Field	Type	Description
`id`	string	Event identifier
`name`	string	Event display name
`company`	string	Company name
`bands`	array	Valuation band definitions
`bands[].id`	string	Band token ID
`bands[].label`	string	Band label (e.g., "$200B+")
`bands[].minValuation`	number	Minimum valuation in billions
`bands[].maxValuation`	number	Maximum valuation in billions

Response:

json

{
  "events": [
    {
      "id": "spacex-ipo",
      "name": "SpaceX IPO Valuation",
      "company": "SpaceX",
      "bands": [
        {
          "id": "0x1234...band1",
          "label": "$200B+",
          "minValuation": 200,
          "maxValuation": null
        },
        {
          "id": "0x1234...band2",
          "label": "$175-200B",
          "minValuation": 175,
          "maxValuation": 200
        }
      ]
    }
  ]
}

Try it — List Events

Set your API key in the nav bar to try this endpoint.

Get Valuation & Pricing Public

GET /api/trading/valuation

Get current band prices, position costs, and bid-ask spread (slippage) for a specific event.

Parameter	Type	Required	Description
`eventSlug`	string	Yes	Event slug (e.g., `openai-ipo-closing-market-cap`)

Response Fields:

Field	Type	Description
`event`	object	Event metadata (name, slug, bands)
`bands`	array	Current band prices from Gamma API
`valuation`	object	Position costs based on mid prices
`slippage`	object	Bid-ask spread data for realistic trading costs
`breakdown`	array	Per-band weight and return calculations
`settings`	object	Floor payoff settings used

Slippage Object:

The slippage field shows the difference between buying (at ask) and selling (at bid):

Field	Type	Description
`long.buyCost`	number	Weighted cost to buy LONG at ask prices
`long.sellValue`	number	Weighted value if selling LONG at bid prices
`long.spread`	number	Absolute spread (buyCost - sellValue)
`long.spreadPercent`	number	Spread as percentage of buy cost
`short.buyCost`	number	Weighted cost to buy SHORT at ask prices
`short.sellValue`	number	Weighted value if selling SHORT at bid prices
`short.spread`	number	Absolute spread (buyCost - sellValue)
`short.spreadPercent`	number	Spread as percentage of buy cost
`bandPrices`	array	Per-band bid/ask prices from order book

Response:

json

{
  "event": {
    "name": "OpenAI",
    "slug": "openai-ipo-closing-market-cap",
    "numBands": 7
  },
  "bands": [
    {
      "bandIndex": 0,
      "label": "< $500B",
      "price": 0.032,
      "tokenId": "6122912..."
    }
  ],
  "valuation": {
    "longCost": 0.839,
    "shortCost": 0.294,
    "bestLongReturn": 19.16,
    "worstLongReturn": -76.17,
    "bestShortReturn": 239.93,
    "worstShortReturn": -49.01
  },
  "slippage": {
    "long": {
      "buyCost": 4.186,
      "sellValue": 0.013,
      "spread": 4.173,
      "spreadPercent": 99.68
    },
    "short": {
      "buyCost": 4.019,
      "sellValue": 0.005,
      "spread": 4.014,
      "spreadPercent": 99.87
    },
    "bandPrices": [
      { "bandIndex": 0, "bid": 0.001, "ask": 0.999 },
      { "bandIndex": 1, "bid": 0.001, "ask": 0.999 }
    ]
  },
  "settings": {
    "floorL": 0.2,
    "floorS": 0.15
  },
  "totalVolume": 1550585.55,
  "endDate": "2026-12-31T23:55:00Z",
  "timestamp": "2026-04-02T17:54:42.474Z"
}

Try it — Get Valuation

Set your API key in the nav bar to try this endpoint.

Get All Valuations Public

GET /api/trading/valuation/all

Get pricing data for all supported events.

Response:

json

{
  "valuations": [
    {
      "eventId": "spacex-ipo",
      "impliedValuation": 185.5,
      "longCost": 127.50,
      "shortCost": 98.25,
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Try it — Get All Valuations

Set your API key in the nav bar to try this endpoint.

Trading

Buy Position Auth Required

POST /api/trading/buy

Open a LONG or SHORT position.

Parameter	Type	Required	Description
`eventId`	string	Yes	Event to trade
`side`	string	Yes	`LONG` or `SHORT`
`amount`	number	Yes	Position size in USD
`floorL`	number	No	Custom floor for LONG (overrides settings)
`floorS`	number	No	Custom floor for SHORT (overrides settings)

Response:

json

{
  "positionId": "pos_abc123",
  "orders": [
    {
      "orderId": "ord_001",
      "bandId": "0x1234...band1",
      "side": "BUY",
      "price": 0.35,
      "size": 50,
      "status": "MATCHED"
    }
  ],
  "totalCost": 100.00,
  "averagePrice": 0.312
}

Try it — Buy Position

Set your API key in the nav bar to try this endpoint.

Sell Position Auth Required

POST /api/trading/sell

Close or reduce a position.

Parameter	Type	Required	Description
`positionId`	string	Yes	Position to sell
`percentage`	number	No	Percentage to sell (1-100, default 100)

Response:

json

{
  "positionId": "pos_abc123",
  "orders": [
    {
      "orderId": "ord_003",
      "bandId": "0x1234...band1",
      "side": "SELL",
      "price": 0.38,
      "size": 50,
      "status": "MATCHED"
    }
  ],
  "totalProceeds": 112.50,
  "realizedPnl": 12.50
}

Try it — Sell Position

Set your API key in the nav bar to try this endpoint.

Position Management

List Positions Auth Required

GET /api/trading/positions

Get all open positions.

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `open`, `closed`, `all`
`eventId`	string	No	Filter by event

Response:

json

{
  "positions": [
    {
      "id": "pos_abc123",
      "eventId": "spacex-ipo",
      "side": "LONG",
      "entryPrice": 0.312,
      "currentPrice": 0.345,
      "size": 100,
      "cost": 100.00,
      "currentValue": 110.58,
      "unrealizedPnl": 10.58,
      "unrealizedPnlPercent": 10.58,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Try it — List Positions

Set your API key in the nav bar to try this endpoint.

Get Position Details Auth Required

GET /api/trading/positions/:id

Get detailed information about a specific position.

Response:

json

{
  "id": "pos_abc123",
  "eventId": "spacex-ipo",
  "side": "LONG",
  "floorL": 0.2,
  "entryPrice": 0.312,
  "currentPrice": 0.345,
  "bands": [
    {
      "bandId": "0x1234...band1",
      "label": "$200B+",
      "tokens": 50,
      "entryPrice": 0.35,
      "currentPrice": 0.38
    }
  ],
  "cost": 100.00,
  "currentValue": 110.58,
  "unrealizedPnl": 10.58,
  "createdAt": "2024-01-15T10:30:00Z"
}

Try it — Get Position

Set your API key in the nav bar to try this endpoint.

Get Position Value Auth Required

GET /api/trading/positions/:id/value

Get current market value of a position.

Response:

json

{
  "positionId": "pos_abc123",
  "currentValue": 110.58,
  "unrealizedPnl": 10.58,
  "unrealizedPnlPercent": 10.58,
  "bandValues": [
    {
      "bandId": "0x1234...band1",
      "tokens": 50,
      "value": 19.00
    }
  ],
  "updatedAt": "2024-01-15T12:00:00Z"
}

Try it — Get Position Value

Set your API key in the nav bar to try this endpoint.

Sync Positions Auth Required

POST /api/trading/positions/sync

Synchronize positions with on-chain data.

Parameter	Type	Required	Description
`walletAddress`	string	No	Wallet to sync (defaults to configured wallet)

Response:

json

{
  "synced": 3,
  "added": 1,
  "removed": 0,
  "positions": [
    {
      "id": "pos_abc123",
      "eventId": "spacex-ipo",
      "side": "LONG",
      "onChainVerified": true
    }
  ]
}

Try it — Sync Positions

Set your API key in the nav bar to try this endpoint.

Orders

List Orders Auth Required

GET /api/trading/orders

Get all orders with optional filtering.

Parameter	Type	Required	Description
`status`	string	No	Filter: `pending`, `matched`, `cancelled`, `all`
`positionId`	string	No	Filter by position
`limit`	number	No	Max results (default 50)

Response:

json

{
  "orders": [
    {
      "id": "ord_001",
      "positionId": "pos_abc123",
      "bandId": "0x1234...band1",
      "side": "BUY",
      "price": 0.35,
      "size": 50,
      "filled": 50,
      "status": "MATCHED",
      "createdAt": "2024-01-15T10:30:00Z",
      "matchedAt": "2024-01-15T10:30:05Z"
    }
  ]
}

Try it — List Orders

Set your API key in the nav bar to try this endpoint.

Get Order Details Auth Required

GET /api/trading/orders/:orderId

Get details for a specific order.

Response:

json

{
  "id": "ord_001",
  "positionId": "pos_abc123",
  "bandId": "0x1234...band1",
  "bandLabel": "$200B+",
  "side": "BUY",
  "price": 0.35,
  "size": 50,
  "filled": 50,
  "remaining": 0,
  "status": "MATCHED",
  "txHash": "0xabc...def",
  "createdAt": "2024-01-15T10:30:00Z",
  "matchedAt": "2024-01-15T10:30:05Z"
}

Try it — Get Order

Set your API key in the nav bar to try this endpoint.

Sync Orders Auth Required

POST /api/trading/orders/sync

Synchronize order status with exchange.

Response:

json

{
  "synced": 5,
  "updated": 2,
  "orders": [
    {
      "id": "ord_001",
      "previousStatus": "PENDING",
      "currentStatus": "MATCHED"
    }
  ]
}

Try it — Sync Orders

Set your API key in the nav bar to try this endpoint.

History

Get Trade History Auth Required

GET /api/trading/history

Retrieve historical trades with P&L data.

Parameter	Type	Required	Description
`eventId`	string	No	Filter by event
`startDate`	string	No	ISO 8601 start date
`endDate`	string	No	ISO 8601 end date
`limit`	number	No	Max results (default 100)
`offset`	number	No	Pagination offset

Response:

json

{
  "trades": [
    {
      "id": "trade_001",
      "positionId": "pos_abc123",
      "eventId": "spacex-ipo",
      "side": "LONG",
      "action": "BUY",
      "amount": 100.00,
      "price": 0.312,
      "fees": 0.50,
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "summary": {
    "totalTrades": 2,
    "totalVolume": 212.50,
    "totalFees": 1.06,
    "realizedPnl": 12.00
  }
}

Try it — Get History

Set your API key in the nav bar to try this endpoint.

Environment Variables

Required environment variables for trading functionality:

Variable	Description
`TRADING_ENCRYPTION_KEY`	64-character hex string for AES-256-GCM encryption of credentials
`POLYGON_RPC_URL`	Polygon RPC endpoint for on-chain verification (optional)

Example:

bash

TRADING_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
POLYGON_RPC_URL=https://polygon-rpc.com

Error Codes

Code	Description
`INVALID_CREDENTIALS`	Polymarket credentials invalid or expired
`INSUFFICIENT_BALANCE`	Insufficient USDC balance for trade
`POSITION_NOT_FOUND`	Requested position does not exist
`ORDER_REJECTED`	Order rejected by exchange
`RATE_LIMITED`	Too many requests, retry later
`INVALID_FLOOR`	Floor payoff value out of range (0-1)

Trading ​

Authentication ​

Public Endpoints (No Auth Required) ​

Protected Endpoints (Auth Required) ​

Overview ​

Key Concepts ​

Supported Events ​

Settings & Credentials ​

Get Trading Settings Auth Required ​

Try it — Get Settings ​

Update Trading Settings Auth Required ​

Try it — Update Settings ​

Set Polymarket Credentials Auth Required ​

Try it — Set Credentials ​

Delete Polymarket Credentials Auth Required ​

Try it — Delete Credentials ​

Market Data ​

List Supported Events Public ​

Try it — List Events ​

Get Valuation & Pricing Public ​

Try it — Get Valuation ​

Get All Valuations Public ​

Try it — Get All Valuations ​

Trading ​

Buy Position Auth Required ​

Try it — Buy Position ​

Sell Position Auth Required ​

Try it — Sell Position ​

Position Management ​

List Positions Auth Required ​

Try it — List Positions ​

Get Position Details Auth Required ​

Try it — Get Position ​

Get Position Value Auth Required ​

Try it — Get Position Value ​

Sync Positions Auth Required ​

Try it — Sync Positions ​

Orders ​

List Orders Auth Required ​

Try it — List Orders ​

Get Order Details Auth Required ​

Try it — Get Order ​

Sync Orders Auth Required ​

Try it — Sync Orders ​

History ​

Get Trade History Auth Required ​

Try it — Get History ​

Environment Variables ​

Error Codes ​

Trading

Authentication

Public Endpoints (No Auth Required)

Protected Endpoints (Auth Required)

Overview

Key Concepts

Supported Events

Settings & Credentials

Get Trading Settings Auth Required

Try it — Get Settings

Update Trading Settings Auth Required

Try it — Update Settings

Set Polymarket Credentials Auth Required

Try it — Set Credentials

Delete Polymarket Credentials Auth Required

Try it — Delete Credentials

Market Data

List Supported Events Public

Try it — List Events

Get Valuation & Pricing Public

Try it — Get Valuation

Get All Valuations Public

Try it — Get All Valuations

Trading

Buy Position Auth Required

Try it — Buy Position

Sell Position Auth Required

Try it — Sell Position

Position Management

List Positions Auth Required

Try it — List Positions

Get Position Details Auth Required

Try it — Get Position

Get Position Value Auth Required

Try it — Get Position Value

Sync Positions Auth Required

Try it — Sync Positions

Orders

List Orders Auth Required

Try it — List Orders

Get Order Details Auth Required

Try it — Get Order

Sync Orders Auth Required

Try it — Sync Orders

History

Get Trade History Auth Required

Try it — Get History

Environment Variables

Error Codes