Integration Guide

This guide provides comprehensive instructions for integrating with VORT, whether you're a trader using the web dashboard, a developer building applications, or a protocol integrating VORT's execution capabilities.

For Traders

The VORT Dashboard provides an intuitive interface for traders to submit intents, monitor execution, and manage their DeFi strategies without requiring technical expertise.

Dashboard Overview

The VORT Dashboard is designed with a clean, modern interface optimized for the VORT visual style: Clean Blue (#0044FF), Dark Mode, Technical, Precision. The dashboard provides:

Intent Creation Interface: An intuitive interface for creating new intents through guided forms, natural language input, or template selection.

Live Execution Feed: Real-time monitoring of intent execution, showing progress, state changes, and execution details as they happen.

Portfolio Management: Tools for managing portfolios, viewing positions, and tracking performance across multiple protocols.

Analytics and Reporting: Comprehensive analytics on execution quality, costs, and performance, with customizable reports and visualizations.

Settings and Preferences: Configuration of user policies, preferences, and integration settings.

Creating Your First Intent

To create your first intent using the dashboard:

Step 1: Connect Your Wallet

• Click "Connect Wallet" in the dashboard header

• Select your Solana wallet (Phantom, Solflare, etc.)

• Approve the connection request

• Your wallet address will be displayed in the header

Step 2: Navigate to Intent Creation

• Click "Create New Intent" in the main navigation or dashboard home

• You'll see three intent creation options:

  • Guided Form: Step-by-step forms for common intent types

  • Natural Language: Type your intent in plain English

  • Templates: Pre-built templates for common strategies

Step 3: Choose Intent Type

• Swap: Exchange one token for another

• Rebalance: Adjust portfolio allocation

• Yield Optimization: Maximize yield across protocols

• Risk Management: Set up stop-losses, leverage limits, etc.

• Custom: Define your own intent

Step 4: Define Intent Parameters

• Target State: What you want to achieve (e.g., "40% SOL, 30% USDC, 30% BTC")

• Constraints: Limits and preferences (e.g., "max slippage 0.5%")

• Timing: When to execute (immediate, scheduled, conditional)

• Policies: Apply your saved policies or create intent-specific policies

Step 5: Review and Submit

• Review your intent summary

• Verify that all parameters are correct

• Check estimated costs and execution time

• Click "Submit Intent" to publish to the Agent Exchange

Step 6: Monitor Execution

• Your intent will appear in the "Live Feed" section

• Watch real-time progress updates

• View execution details as they happen

• Receive notifications when execution completes

Live Feed Features

The Live Feed provides real-time visibility into intent execution:

Execution Status: See the current status of each intent (pending, in auction, executing, completed, failed).

Progress Indicators: Visual progress bars and status indicators show how far execution has progressed.

State Snapshots: View on-chain state snapshots at key execution milestones, seeing how your portfolio or positions change during execution.

Agent Information: See which agents are handling your intents, their reputation scores, and execution strategies.

Cost Tracking: Real-time tracking of execution costs (fees, gas, agent commissions) as they accumulate.

Error Reporting: If errors occur, detailed error reports are displayed immediately with explanations and remediation options.

Execution Timeline: A timeline view shows all execution events in chronological order, enabling detailed analysis of what happened and when.

Portfolio Management

The Portfolio section provides comprehensive portfolio management:

Portfolio Overview: High-level view of your portfolio across all protocols:

• Total value and allocation percentages

• Performance metrics (gains/losses, yield, etc.)

• Risk metrics (leverage, health factors, etc.)

Position Details: Detailed view of individual positions:

• Protocol-specific positions (Drift, Kamino, etc.)

• Position parameters (leverage, collateral, etc.)

• Performance and risk metrics

• Historical performance

Multi-Protocol View: Unified view of positions across multiple protocols, enabling understanding of your complete DeFi exposure.

Rebalancing Tools: Tools for creating rebalancing intents based on target allocations or risk parameters.

Yield Optimization: Tools for optimizing yield across lending and staking protocols.

Analytics and Reporting

The Analytics section provides comprehensive execution analysis:

Execution Quality: Analysis of how well your intents were fulfilled:

• Outcome accuracy (achieved vs. target state)

• Price efficiency (execution prices vs. market rates)

• Slippage analysis

• Cost breakdowns

Performance Trends: Historical performance trends:

• Execution quality over time

• Cost trends

• Success rates

• Agent performance

Comparative Analysis: Comparison of execution to alternatives:

• What would manual execution have achieved?

• How do VORT executions compare to other aggregators?

• Performance vs. historical patterns

Custom Reports: Generate custom reports on specific time periods, intent types, or performance metrics.

Export Options: Export analytics data for external analysis or record-keeping.

For Developers

Developers can integrate VORT into their applications using the VORT SDK, enabling programmatic intent submission and execution monitoring.

Installing the VORT SDK

The VORT SDK is available for multiple languages and platforms:

JavaScript/TypeScript (Node.js and Browser)

npm install @vort-protocol/sdk

Python

pip install vort-sdk

Rust

[dependencies]
vort-sdk = "0.1.0"

Go

go get github.com/vort-protocol/sdk-go

SDK Initialization

Initialize the SDK with your configuration:

JavaScript/TypeScript Example

import { VORT } from '@vort-protocol/sdk';

const vort = new VORT({
  apiKey: 'your-api-key', // Optional, for authenticated access
  network: 'mainnet', // 'mainnet' or 'devnet'
  rpcUrl: 'https://api.mainnet-beta.solana.com', // Optional, custom RPC
});

Python Example

from vort_sdk import VORT

vort = VORT(
    api_key='your-api-key',  # Optional
    network='mainnet',
    rpc_url='https://api.mainnet-beta.solana.com'  # Optional
)

Your First Intent

Here's a complete example of submitting your first intent programmatically:

JavaScript/TypeScript Example

import { VORT } from '@vort-protocol/sdk';
import { Wallet } from '@solana/web3.js';

// Initialize SDK
const vort = new VORT({ network: 'mainnet' });

// Load user wallet (example using @solana/web3.js)
const wallet = await loadWallet(); // Your wallet loading logic

// Define intent
const intent = {
  type: 'rebalance',
  target: {
    SOL: 0.4,  // 40%
    USDC: 0.3, // 30%
    BTC: 0.3   // 30%
  },
  constraints: {
    maxSlippage: 0.005, // 0.5%
    maxGasCost: 0.01,   // 0.01 SOL
  },
  policies: {
    preferredProtocols: ['Jupiter', 'Drift'],
  }
};

// Submit intent
const result = await vort.submitIntent(intent, {
  wallet: wallet,
  signMessage: async (message) => {
    // Sign message with user's wallet
    return await wallet.signMessage(message);
  }
});

console.log('Intent submitted:', result.intentId);
console.log('Status:', result.status);

// Monitor execution
const execution = await vort.monitorIntent(result.intentId);
execution.on('progress', (update) => {
  console.log('Progress:', update);
});
execution.on('complete', (receipt) => {
  console.log('Execution complete:', receipt);
});
execution.on('error', (error) => {
  console.error('Execution error:', error);
});

Python Example

from vort_sdk import VORT
from solana.keypair import Keypair

# Initialize SDK
vort = VORT(network='mainnet')

# Load user wallet
wallet = load_wallet()  # Your wallet loading logic

# Define intent
intent = {
    'type': 'rebalance',
    'target': {
        'SOL': 0.4,   # 40%
        'USDC': 0.3,  # 30%
        'BTC': 0.3    # 30%
    },
    'constraints': {
        'max_slippage': 0.005,  # 0.5%
        'max_gas_cost': 0.01,   # 0.01 SOL
    },
    'policies': {
        'preferred_protocols': ['Jupiter', 'Drift'],
    }
}

# Submit intent
result = vort.submit_intent(
    intent=intent,
    wallet=wallet,
    sign_message=lambda msg: wallet.sign(msg)
)

print(f'Intent submitted: {result.intent_id}')
print(f'Status: {result.status}')

# Monitor execution
execution = vort.monitor_intent(result.intent_id)
execution.on_progress(lambda update: print(f'Progress: {update}'))
execution.on_complete(lambda receipt: print(f'Execution complete: {receipt}'))
execution.on_error(lambda error: print(f'Execution error: {error}'))

Intent Types

VORT supports multiple intent types, each with specific parameters:

Swap Intent: Exchange tokens

const swapIntent = {
  type: 'swap',
  from: 'SOL',
  to: 'USDC',
  amount: 100, // or percentage of balance
  constraints: {
    maxSlippage: 0.005,
    preferredRoute: 'Jupiter',
  }
};

Rebalance Intent: Adjust portfolio allocation

const rebalanceIntent = {
  type: 'rebalance',
  target: { SOL: 0.4, USDC: 0.3, BTC: 0.3 },
  constraints: {
    maxSlippage: 0.005,
    rebalanceThreshold: 0.05, // Rebalance if drift > 5%
  }
};

Yield Optimization Intent: Maximize yield

const yieldIntent = {
  type: 'yield_optimize',
  assets: ['USDC', 'SOL'],
  constraints: {
    maxRisk: 7, // Risk score out of 10
    minLiquidity: 0.2, // Maintain 20% liquidity
  }
};

Risk Management Intent: Set up risk controls

const riskIntent = {
  type: 'risk_manage',
  actions: [
    {
      condition: 'health_factor < 1.2',
      action: 'reduce_leverage',
      target: 1.5
    },
    {
      condition: 'position_size > 10000',
      action: 'reduce_position',
      target: 10000
    }
  ]
};

Monitoring Execution

Monitor intent execution in real-time:

Event-Based Monitoring

const execution = await vort.monitorIntent(intentId);

execution.on('submitted', () => {
  console.log('Intent submitted to Agent Exchange');
});

execution.on('auction', (auction) => {
  console.log('Auction in progress:', auction);
});

execution.on('executing', (progress) => {
  console.log('Execution progress:', progress);
  console.log('Current state:', progress.currentState);
  console.log('Actions completed:', progress.actionsCompleted);
});

execution.on('complete', (receipt) => {
  console.log('Execution complete!');
  console.log('Final state:', receipt.finalState);
  console.log('Execution proof:', receipt.proof);
});

execution.on('error', (error) => {
  console.error('Execution error:', error);
  console.error('Error details:', error.details);
});

Polling-Based Monitoring

// Poll for status updates
const status = await vort.getIntentStatus(intentId);
console.log('Current status:', status.status);
console.log('Progress:', status.progress);
console.log('Current state:', status.currentState);

// Get execution receipt when complete
if (status.status === 'completed') {
  const receipt = await vort.getExecutionReceipt(intentId);
  console.log('Execution receipt:', receipt);
}

Error Handling

Handle errors gracefully:

try {
  const result = await vort.submitIntent(intent, { wallet, signMessage });
  // Handle success
} catch (error) {
  if (error.code === 'INVALID_INTENT') {
    // Intent validation failed
    console.error('Invalid intent:', error.details);
  } else if (error.code === 'INSUFFICIENT_BALANCE') {
    // User doesn't have sufficient balance
    console.error('Insufficient balance:', error.details);
  } else if (error.code === 'POLICY_VIOLATION') {
    // Intent violates user policies
    console.error('Policy violation:', error.details);
  } else {
    // Other errors
    console.error('Unexpected error:', error);
  }
}

Best Practices

Follow these best practices for optimal integration:

Intent Validation: Validate intents before submission to catch errors early and provide better user feedback.

Error Handling: Implement comprehensive error handling for all SDK operations, providing clear error messages to users.

Status Polling: For long-running intents, implement status polling with appropriate intervals to avoid excessive API calls.

Receipt Storage: Store execution receipts for audit trails and future reference.

User Feedback: Provide clear feedback to users about intent status, progress, and outcomes.

Cost Estimation: Estimate and display execution costs before submission to set user expectations.

Policy Management: Allow users to configure and manage policies through your application interface.

This integration guide provides the foundation for building applications on VORT. For detailed API reference, see the SDK documentation. For proof verification, see the Proof Verification guide.