Skip to main content
GET
/
positions
/
{wallet_address}
/
queue-positions
curl -X GET "https://api.strike.markets/positions/0x742d35cc6C6C7532B1140Da4C8A2f6C8ECfC9B46/queue-positions"
{
  "12346": {
    "position_id": 12346,
    "queue_position_usd": 1250.75,
    "margin": 200.0,
    "realized_pnl": 20.0,
    "net_payout": 220.0,
    "position_in_queue": 3,
    "estimated_payout_time": "2024-01-17T10:30:00Z"
  },
  "12347": {
    "position_id": 12347,
    "queue_position_usd": 3500.25,
    "margin": 500.0,
    "realized_pnl": 150.0,
    "net_payout": 650.0,
    "position_in_queue": 8,
    "estimated_payout_time": "2024-01-18T14:15:00Z"
  }
}
curl -X GET "https://api.strike.markets/positions/0x742d35cc6C6C7532B1140Da4C8A2f6C8ECfC9B46/queue-positions"
{
  "12346": {
    "position_id": 12346,
    "queue_position_usd": 1250.75,
    "margin": 200.0,
    "realized_pnl": 20.0,
    "net_payout": 220.0,
    "position_in_queue": 3,
    "estimated_payout_time": "2024-01-17T10:30:00Z"
  },
  "12347": {
    "position_id": 12347,
    "queue_position_usd": 3500.25,
    "margin": 500.0,
    "realized_pnl": 150.0,
    "net_payout": 650.0,
    "position_in_queue": 8,
    "estimated_payout_time": "2024-01-18T14:15:00Z"
  }
}

Overview

Get payout queue information for positions that have been closed but are waiting for settlement. When the protocol treasury has insufficient funds to immediately pay out closed positions, they are placed in a First-In-First-Out (FIFO) payout queue.
This endpoint does NOT require authentication and provides queue status information for any wallet address.

Path Parameters

wallet_address
string
required
Ethereum wallet address to check queue positions for.Format: 42-character hex string starting with “0x”
Example: “0x742d35cc6C6C7532B1140Da4C8A2f6C8ECfC9B46”

Response Structure

The response is a dictionary where each key is a position ID (as string) and the value contains queue information for that specific position.

Queue Entry Properties

position_id
integer
The position ID that is in the payout queue
queue_position_usd
number
USD amount ahead of this position in the queue
margin
number
Original margin amount for this position
realized_pnl
number
Realized profit/loss when position was closed
net_payout
number
Total amount to be paid out (margin + realized_pnl)
position_in_queue
integer
Numerical position in the payout queue (1 = next to be paid)
estimated_payout_time
string
Estimated ISO timestamp when payout will be processed

Payout Queue Mechanics

How the Queue Works

Position Closure

When you close a position:
  1. PnL Calculation: System calculates your profit/loss
  2. Payout Amount: Determines net amount owed to you
  3. Treasury Check: Verifies if treasury has sufficient funds
  4. Settlement Type: Immediate payout or queue placement

Queue Placement

Positions enter the queue when:
  • Treasury insufficient: Not enough funds for immediate payout
  • Large payouts: Significant wins that exceed available treasury
  • High volume periods: Multiple large payouts occurring simultaneously

Processing Order

Queue operates on First-In-First-Out (FIFO) basis:
  • Position 1: Next to be paid when funds are available
  • Position 2: Second in line
  • Position N: Your position number in the queue

Treasury Management

Funding Sources

Treasury receives funds from:
  • Trading fees: Collected from all position operations
  • Liquidation proceeds: Assets from liquidated positions
  • Protocol revenue: Various protocol fee streams
  • Emergency reserves: Additional funds if needed

Payout Processing

  • Continuous monitoring: System checks treasury balance regularly
  • Automatic processing: Pays queue positions as funds become available
  • Batch payments: May process multiple queue positions simultaneously
  • No manual intervention: Fully automated payout system

Queue Status Information

Queue Position

Your position number indicates:
  • Position 1: You’re next to be paid
  • Position 2-5: High priority, typically paid within hours
  • Position 6-20: Medium priority, usually paid within 24 hours
  • Position 20+: Lower priority, may take longer depending on treasury flow

USD Ahead

The amount ahead of you represents:
  • Total payouts: Sum of all payouts before yours in the queue
  • Treasury requirement: How much the treasury needs before your turn
  • Processing indicator: Helps estimate payout timing

Estimated Processing Time

While not guaranteed, typical processing times:
  • 0-1000 USD ahead: Usually within 1-6 hours
  • 1000-5000 USD ahead: Typically 6-24 hours
  • 5000-20000 USD ahead: Usually 1-3 days
  • 20000+ USD ahead: May take longer, depends on treasury inflow

Use Cases

Payout Tracking

  • Monitor progress: Track your position in the queue
  • Estimate timing: Get rough idea of when you’ll be paid
  • Plan finances: Know when funds will be available
  • Set expectations: Understand payout delays are temporary

User Communication

  • Status updates: Inform users about their queue position
  • Progress indicators: Show movement through the queue
  • Transparency: Provide clear information about payout status
  • Education: Explain why some payouts are delayed

System Monitoring

  • Queue length: Monitor overall queue health
  • Treasury status: Understand protocol liquidity
  • Processing rate: Track how quickly queue moves
  • Anomaly detection: Identify unusual queue buildup

Error Responses

400 Bad Request
object
Invalid wallet address format
{
  "error": 400,
  "message": "Invalid wallet address format"
}
404 Not Found
object
No queue positions found for this wallet (no pending payouts)
{
  "error": 404,
  "message": "No positions in payout queue for this wallet"
}

Usage Examples

Check Queue Status

async function checkQueueStatus(walletAddress) {
  try {
    const response = await fetch(`https://api.strike.markets/positions/${walletAddress}/queue-positions`);
    
    if (response.status === 404) {
      return { message: "No positions in queue", inQueue: false };
    }
    
    const data = await response.json();
    
    return {
      inQueue: true,
      position: data.queuePosition,
      usdAhead: parseFloat(data.usdAhead),
      estimatedWait: estimateWaitTime(data.queuePosition, data.usdAhead)
    };
  } catch (error) {
    console.error('Failed to check queue status:', error);
    return { error: 'Failed to fetch queue information' };
  }
}

function estimateWaitTime(position, usdAhead) {
  if (usdAhead < 1000) return 'Within 6 hours';
  if (usdAhead < 5000) return '6-24 hours';
  if (usdAhead < 20000) return '1-3 days';
  return 'Several days';
}

Monitor Queue Progress

class QueueMonitor {
  constructor(walletAddress, onUpdate) {
    this.walletAddress = walletAddress;
    this.onUpdate = onUpdate;
    this.lastPosition = null;
    this.lastAmount = null;
  }
  
  async start() {
    this.check();
    this.timer = setInterval(() => this.check(), 30000); // Check every 30 seconds
  }
  
  stop() {
    if (this.timer) clearInterval(this.timer);
  }
  
  async check() {
    try {
      const response = await fetch(`https://api.strike.markets/positions/${this.walletAddress}/queue-positions`);
      
      if (response.status === 404) {
        // Not in queue anymore - likely paid out!
        if (this.lastPosition !== null) {
          this.onUpdate({ 
            event: 'payout_completed',
            message: 'Your payout has been processed!' 
          });
          this.stop();
        }
        return;
      }
      
      const data = await response.json();
      
      if (this.lastPosition !== null) {
        if (data.queuePosition < this.lastPosition) {
          this.onUpdate({
            event: 'position_improved',
            oldPosition: this.lastPosition,
            newPosition: data.queuePosition,
            message: `Moved up in queue: position ${this.lastPosition}${data.queuePosition}`
          });
        }
        
        const amountChange = this.lastAmount - parseFloat(data.usdAhead);
        if (amountChange > 10) { // More than 10 USD processed
          this.onUpdate({
            event: 'queue_processed',
            amountProcessed: amountChange,
            remaining: data.usdAhead,
            message: `$${amountChange.toFixed(2)} processed ahead of you`
          });
        }
      }
      
      this.lastPosition = data.queuePosition;
      this.lastAmount = parseFloat(data.usdAhead);
      
      this.onUpdate({
        event: 'status_update',
        position: data.queuePosition,
        usdAhead: data.usdAhead
      });
      
    } catch (error) {
      this.onUpdate({
        event: 'error',
        message: 'Failed to check queue status'
      });
    }
  }
}

// Usage
const monitor = new QueueMonitor(walletAddress, (update) => {
  console.log('Queue update:', update);
  
  switch(update.event) {
    case 'payout_completed':
      showNotification('Payout completed!', 'success');
      break;
    case 'position_improved':
      showNotification(`Moved to position ${update.newPosition}`, 'info');
      break;
    case 'queue_processed':
      showNotification(`$${update.amountProcessed} processed`, 'info');
      break;
  }
});

monitor.start();

Queue Progress Visualization

function QueueProgressBar({ queuePosition, usdAhead }) {
  const getProgressData = () => {
    const totalEstimated = usdAhead + 1000; // Estimate total queue size
    const progress = (1000 / totalEstimated) * 100;
    
    return {
      progress: Math.max(progress, 5), // Minimum 5% to show some progress
      positionText: `Position ${queuePosition} in queue`,
      amountText: `$${parseFloat(usdAhead).toFixed(2)} ahead`,
      estimatedTime: getEstimatedTime(usdAhead)
    };
  };
  
  const getEstimatedTime = (amount) => {
    if (amount < 1000) return 'Within 6 hours';
    if (amount < 5000) return '6-24 hours';
    if (amount < 20000) return '1-3 days';
    return 'Several days';
  };
  
  const data = getProgressData();
  
  return (
    <div className="queue-progress">
      <div className="progress-header">
        <span className="position">{data.positionText}</span>
        <span className="amount">{data.amountText}</span>
      </div>
      <div className="progress-bar">
        <div 
          className="progress-fill" 
          style={{ width: `${data.progress}%` }}
        />
      </div>
      <div className="estimated-time">
        Estimated payout time: {data.estimatedTime}
      </div>
    </div>
  );
}

Queue Analytics

async function getQueueAnalytics(walletAddress) {
  try {
    const response = await fetch(`https://api.strike.markets/positions/${walletAddress}/queue-positions`);
    
    if (response.status === 404) {
      return { inQueue: false, message: "No positions in payout queue" };
    }
    
    const data = await response.json();
    const usdAhead = parseFloat(data.usdAhead);
    
    // Calculate analytics
    const analytics = {
      queuePosition: data.queuePosition,
      usdAhead: usdAhead,
      priority: getPriority(data.queuePosition),
      estimatedHours: estimateHours(usdAhead),
      percentileRank: calculatePercentile(data.queuePosition, usdAhead),
      recommendedAction: getRecommendation(data.queuePosition, usdAhead)
    };
    
    return analytics;
  } catch (error) {
    return { error: 'Failed to fetch queue analytics' };
  }
}

function getPriority(position) {
  if (position <= 5) return 'HIGH';
  if (position <= 20) return 'MEDIUM';
  return 'LOW';
}

function estimateHours(usdAhead) {
  if (usdAhead < 1000) return '1-6';
  if (usdAhead < 5000) return '6-24';
  if (usdAhead < 20000) return '24-72';
  return '72+';
}

function calculatePercentile(position, amount) {
  // Simplified percentile calculation
  // In practice, you might track historical queue data
  const score = (1 / position) * 100 + (1 / (amount / 1000)) * 100;
  return Math.min(Math.max(score, 1), 99).toFixed(1);
}

function getRecommendation(position, amount) {
  if (position <= 3) return 'Your payout should process very soon. No action needed.';
  if (amount < 5000) return 'You should be paid within 24 hours. Monitor progress.';
  if (amount < 20000) return 'Payout may take 1-3 days. Consider smaller position sizes in future.';
  return 'Significant queue ahead. Consider risk management for future trades.';
}

Integration Best Practices

User Experience

  • Clear communication: Explain what queue position means
  • Regular updates: Check queue status periodically
  • Progress indicators: Show visual progress through queue
  • Realistic expectations: Don’t promise specific timeframes

Error Handling

  • Handle 404s gracefully: Not being in queue is often good news
  • Network resilience: Implement retry logic for failed requests
  • User feedback: Provide clear error messages
  • Fallback states: Show appropriate UI when data unavailable

Performance

  • Reasonable polling: Don’t check too frequently (30-60 seconds minimum)
  • Cache briefly: Queue positions don’t change rapidly
  • Batch requests: If checking multiple wallets, space out requests
  • Error backoff: Reduce frequency if errors occur

Queue System Transparency

Why Queues Exist

  • Capital efficiency: Allows leverage without requiring full backing
  • Risk management: Prevents treasury depletion during high volume
  • Fairness: FIFO ensures fair processing order
  • Sustainability: Maintains protocol health during volatile periods

Queue Processing

  • Automated: No manual intervention required
  • Continuous: Processes 24/7 as funds become available
  • Fair: Strictly first-in-first-out ordering
  • Reliable: Guaranteed payout, just potentially delayed

Monitoring and Transparency

  • Public data: Queue positions are transparent and verifiable
  • Real-time updates: Status changes immediately reflect in API
  • No favoritism: All users processed in strict order
  • Predictable: Treasury inflows follow consistent patterns
Queue positions are processed automatically as treasury funds become available. The system operates 24/7 with no manual intervention required.
If you’re frequently in the payout queue, consider smaller position sizes or closing positions during periods of lower network activity.
Queue positions are estimates based on current conditions. Actual processing times may vary depending on treasury inflows and overall system activity.

Path Parameters

wallet_address
string
required

Ethereum wallet address

Response

200 - application/json

Queue positions retrieved successfully

queuePosition
integer

Position in the payout queue

usdAhead
string

USD amount ahead in queue