API Reference

Complete API documentation for Veyra platform integration.

Base URL

Production: https://api.veyramarket.com
Development: https://veyramarket.com/api

Authentication

Wallet-Based Auth

Veyra uses wallet signatures for authentication:

// 1. Get challenge message
GET /api/auth/challenge?wallet={address}

Response:
{
  "challenge": "Sign this message to authenticate: {random_nonce}",
  "timestamp": 1699564800
}

// 2. Sign message with wallet
const signature = await signMessage(challenge);

// 3. Verify signature
POST /api/auth/verify
Body: {
  "wallet": "5yyuoTxxLj36pm3oEm4eYB...",
  "signature": "3Xk8j9mN...",
  "message": "Sign this message..."
}

Response:
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": 1699651200
}

Using Auth Token

Include token in requests:

fetch('https://api.veyra.app/markets', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIs...'
  }
});

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "MARKET_NOT_FOUND",
    "message": "Market with id '123' not found",
    "details": {}
  }
}

Error Codes

400: Bad Request - Invalid parameters
401: Unauthorized - Authentication required
403: Forbidden - Insufficient permissions
404: Not Found - Resource doesn't exist
429: Too Many Requests - Rate limit exceeded
500: Internal Server Error - Server error

Markets API

List Markets

Get all active markets:

GET /api/markets

Query Parameters:
- category (string): Filter by category
- status (string): active|resolved|all
- limit (number): Results per page (default: 50)
- offset (number): Pagination offset (default: 0)
- sort (string): volume|price|date
- order (string): asc|desc

Example:
GET /api/markets?category=crypto&limit=20&sort=volume&order=desc

Response:

{
  "success": true,
  "data": [
    {
      "id": "will-bitcoin-reach-150k",
      "slug": "will-bitcoin-reach-150k",
      "title": "Will Bitcoin reach $150,000 in 2025?",
      "category": "crypto",
      "description": "Market resolves YES if Bitcoin...",
      "endDate": "2025-12-31T23:59:59Z",
      "volume": 8900000,
      "liquidity": 1335000,
      "trending": true,
      "image": "https://picsum.photos/seed/crypto/800/400",
      "outcomes": [
        {
          "id": "yes",
          "label": "Outcome",
          "yesPrice": 0.68,
          "noPrice": 0.32,
          "change24h": 2.5,
          "volume": 8900000
        }
      ],
      "createdAt": "2025-01-15T10:00:00Z",
      "resolved": false
    }
  ],
  "pagination": {
    "total": 520,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Get Market by ID

Get detailed market information:

GET /api/markets/{market_id}

Example:
GET /api/markets/will-bitcoin-reach-150k

Response:

{
  "success": true,
  "data": {
    "id": "will-bitcoin-reach-150k",
    "title": "Will Bitcoin reach $150,000 in 2025?",
    "category": "crypto",
    "description": "This market will resolve to YES if...",
    "endDate": "2025-12-31T23:59:59Z",
    "volume": 8900000,
    "liquidity": 1335000,
    "outcomes": [
      {
        "id": "outcome-1",
        "label": "Outcome",
        "yesPrice": 0.68,
        "noPrice": 0.32,
        "change24h": 2.5,
        "yesShares": 6052000,
        "noShares": 2848000,
        "volume": 8900000
      }
    ],
    "priceHistoryByOutcome": {
      "outcome-1": {
        "2025-10-01": 0.62,
        "2025-10-02": 0.64,
        "2025-10-03": 0.65,
        // ... 30 days
      }
    },
    "orderBook": {
      "bids": [
        { "price": 0.67, "quantity": 5000 },
        { "price": 0.66, "quantity": 8000 }
      ],
      "asks": [
        { "price": 0.69, "quantity": 5000 },
        { "price": 0.70, "quantity": 8000 }
      ]
    },
    "tradeHistory": [
      {
        "id": "trade-1",
        "side": "buy",
        "outcome": "Yes",
        "price": 0.68,
        "quantity": 100,
        "timestamp": "2025-11-04T10:30:00Z"
      }
    ],
    "resolved": false,
    "resolvedOutcome": null
  }
}

Search Markets

Search markets by keyword:

GET /api/markets/search?q={query}

Query Parameters:
- q (string): Search query (required)
- category (string): Filter by category
- limit (number): Results limit

Example:
GET /api/markets/search?q=bitcoin&category=crypto&limit=10

Response:

{
  "success": true,
  "data": [
    {
      "id": "will-bitcoin-reach-150k",
      "title": "Will Bitcoin reach $150,000 in 2025?",
      "category": "crypto",
      "relevance": 0.95
    }
  ],
  "total": 15
}

Trading API

Execute Trade

Place a buy/sell order:

POST /api/trades

Headers:
Authorization: Bearer {token}

Body:
{
  "marketId": "will-bitcoin-reach-150k",
  "outcomeId": "outcome-1",
  "side": "buy",
  "quantity": 100,
  "price": 0.68,
  "signature": "3Xk8j9mN...",
  "walletAddress": "5yyuoTxxLj36pm3oEm4eYB..."
}

Response:

{
  "success": true,
  "data": {
    "tradeId": "trade-abc123",
    "marketId": "will-bitcoin-reach-150k",
    "outcome": "Yes",
    "side": "buy",
    "quantity": 100,
    "price": 0.68,
    "totalCost": 68.00,
    "fee": 1.36,
    "netCost": 69.36,
    "timestamp": "2025-11-04T10:30:00Z",
    "status": "confirmed"
  }
}

Get Trade History

Get user's trade history:

GET /api/trades/history

Headers:
Authorization: Bearer {token}

Query Parameters:
- marketId (string): Filter by market
- status (string): all|open|closed
- limit (number): Results per page
- offset (number): Pagination

Example:
GET /api/trades/history?limit=20&status=all

Response:

{
  "success": true,
  "data": [
    {
      "id": "trade-1",
      "marketId": "will-bitcoin-reach-150k",
      "marketTitle": "Will Bitcoin reach $150,000?",
      "outcome": "Yes",
      "side": "buy",
      "quantity": 100,
      "price": 0.68,
      "totalCost": 68.00,
      "currentValue": 75.00,
      "pnl": 7.00,
      "pnlPercent": 10.29,
      "timestamp": "2025-11-01T14:30:00Z",
      "status": "open"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}

Portfolio API

Get Portfolio

Get user's portfolio overview:

GET /api/portfolio

Headers:
Authorization: Bearer {token}

Response:

{
  "success": true,
  "data": {
    "totalValue": 1247.50,
    "totalInvested": 1000.00,
    "totalPnL": 247.50,
    "totalPnLPercent": 24.75,
    "realizedPnL": 180.00,
    "unrealizedPnL": 67.50,
    "winRate": 66.7,
    "totalTrades": 45,
    "winningTrades": 30,
    "losingTrades": 15,
    "activePositions": 8,
    "resolvedPositions": 37,
    "positions": [
      {
        "marketId": "will-bitcoin-reach-150k",
        "marketTitle": "Will Bitcoin reach $150,000?",
        "outcome": "Yes",
        "shares": 100,
        "avgEntryPrice": 0.68,
        "currentPrice": 0.75,
        "costBasis": 68.00,
        "currentValue": 75.00,
        "unrealizedPnL": 7.00,
        "unrealizedPnLPercent": 10.29,
        "daysHeld": 14
      }
    ],
    "byCategory": {
      "crypto": { "value": 450.00, "pnl": 80.00 },
      "politics": { "value": 320.00, "pnl": 45.00 },
      "sports": { "value": 280.50, "pnl": 60.50 },
      "business": { "value": 197.00, "pnl": 62.00 }
    }
  }
}

Get Position Details

Get specific position:

GET /api/portfolio/positions/{market_id}

Headers:
Authorization: Bearer {token}

Example:
GET /api/portfolio/positions/will-bitcoin-reach-150k

Response:

{
  "success": true,
  "data": {
    "marketId": "will-bitcoin-reach-150k",
    "marketTitle": "Will Bitcoin reach $150,000?",
    "outcome": "Yes",
    "shares": 100,
    "avgEntryPrice": 0.68,
    "currentPrice": 0.75,
    "costBasis": 68.00,
    "currentValue": 75.00,
    "unrealizedPnL": 7.00,
    "unrealizedPnLPercent": 10.29,
    "trades": [
      {
        "id": "trade-1",
        "type": "buy",
        "quantity": 50,
        "price": 0.65,
        "cost": 32.50,
        "timestamp": "2025-11-01T10:00:00Z"
      },
      {
        "id": "trade-2",
        "type": "buy",
        "quantity": 50,
        "price": 0.71,
        "cost": 35.50,
        "timestamp": "2025-11-03T14:30:00Z"
      }
    ]
  }
}

Solana Integration API

Get Treasury Wallet

Get platform treasury wallet address:

GET /api/solana/treasury-wallet

Response:

{
  "success": true,
  "data": {
    "treasuryWallet": "5yyuoTxxLj36pm3oEm4eYB8K7atCFYNQXDqc3sekyrLu"
  }
}

Verify Transaction

Verify Solana transaction:

POST /api/solana/verify-transaction

Body:
{
  "marketId": "will-bitcoin-reach-150k",
  "outcomeId": "outcome-1",
  "side": "buy",
  "shares": 100,
  "pricePerShare": 0.68,
  "walletAddress": "5yyuoTxxLj36pm3oEm4eYB...",
  "signature": "3Xk8j9mN2pL5qR7sT9vW..."
}

Response:

{
  "success": true,
  "data": {
    "transactionId": "veyra_3Xk8j9mN_1699564800",
    "treasuryWallet": "5yyuoTxxLj36pm3oEm4eYB...",
    "amount": 68.00,
    "verified": true,
    "message": "Transaction verified on Solana"
  }
}

Get Transaction Status

Check Solana transaction status:

GET /api/solana/transaction/{signature}

Example:
GET /api/solana/transaction/3Xk8j9mN2pL5qR7sT9vW...

Response:

{
  "success": true,
  "data": {
    "signature": "3Xk8j9mN2pL5qR7sT9vW...",
    "status": "confirmed",
    "slot": 123456789,
    "timestamp": "2025-11-04T10:30:15Z",
    "error": null
  }
}

WebSocket API

Real-Time Market Updates

Connect to WebSocket:

const ws = new WebSocket('wss://api.veyra.app/ws');

// Subscribe to market updates
ws.send(JSON.stringify({
  "action": "subscribe",
  "channel": "market",
  "marketId": "will-bitcoin-reach-150k"
}));

// Receive updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Market update:', data);
};

Market Update Format:

{
  "type": "market_update",
  "marketId": "will-bitcoin-reach-150k",
  "data": {
    "yesPrice": 0.68,
    "noPrice": 0.32,
    "change24h": 2.5,
    "volume": 8900000,
    "lastTrade": {
      "price": 0.68,
      "quantity": 50,
      "side": "buy",
      "timestamp": "2025-11-04T10:30:00Z"
    }
  },
  "timestamp": "2025-11-04T10:30:01Z"
}

Portfolio Updates

Subscribe to portfolio changes:

ws.send(JSON.stringify({
  "action": "subscribe",
  "channel": "portfolio",
  "token": "Bearer eyJhbGciOiJIUzI1NiIs..."
}));

Portfolio Update Format:

{
  "type": "portfolio_update",
  "data": {
    "totalValue": 1255.00,
    "totalPnL": 255.00,
    "change": 7.50,
    "changePercent": 0.60
  },
  "timestamp": "2025-11-04T10:30:01Z"
}

Rate Limiting

Limits

Public Endpoints:
- 100 requests per minute
- 1000 requests per hour

Authenticated Endpoints:
- 300 requests per minute  
- 3000 requests per hour

WebSocket:
- 10 subscriptions per connection
- 1000 messages per minute

Headers

Rate limit info in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564860

Rate Limit Error

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

SDK Examples

JavaScript/TypeScript

import { VeyraClient } from '@veyra/sdk';

const client = new VeyraClient({
  apiKey: 'your_api_key',
  network: 'mainnet'
});

// Get markets
const markets = await client.markets.list({
  category: 'crypto',
  limit: 20
});

// Execute trade
const trade = await client.trades.execute({
  marketId: 'will-bitcoin-reach-150k',
  side: 'buy',
  quantity: 100,
  price: 0.68
});

// Get portfolio
const portfolio = await client.portfolio.get();

Python

from veyra import VeyraClient

client = VeyraClient(
    api_key='your_api_key',
    network='mainnet'
)

# Get markets
markets = client.markets.list(
    category='crypto',
    limit=20
)

# Execute trade
trade = client.trades.execute(
    market_id='will-bitcoin-reach-150k',
    side='buy',
    quantity=100,
    price=0.68
)

# Get portfolio
portfolio = client.portfolio.get()

Webhooks

Register Webhook

Set up event notifications:

POST /api/webhooks

Headers:
Authorization: Bearer {token}

Body:
{
  "url": "https://your-app.com/webhooks/veyra",
  "events": [
    "trade.executed",
    "market.resolved",
    "position.closed"
  ],
  "secret": "your_webhook_secret"
}

Webhook Payload

Market resolved event:

{
  "event": "market.resolved",
  "timestamp": "2025-11-04T10:30:00Z",
  "data": {
    "marketId": "will-bitcoin-reach-150k",
    "winningOutcome": "Yes",
    "resolvedAt": "2025-12-31T23:59:59Z"
  },
  "signature": "sha256=abc123..."
}

Related Documentation:

Solana Integration - Blockchain details
Smart Contracts - Contract interfaces
Security - API security best practices

PreviousSolana Integration NextTokenomics

Last updated 1 month ago

Good evening

Base URL

Authentication

Wallet-Based Auth

Using Auth Token

Response Format

Success Response

Error Response

Error Codes

Markets API

List Markets

Get Market by ID

Search Markets

Trading API

Execute Trade

Get Trade History

Portfolio API

Get Portfolio

Get Position Details

Solana Integration API

Get Treasury Wallet

Verify Transaction

Get Transaction Status

WebSocket API

Real-Time Market Updates

Portfolio Updates

Rate Limiting

Limits

Headers

Rate Limit Error

SDK Examples

JavaScript/TypeScript

Python

Webhooks

Register Webhook

Webhook Payload