SDK

Initialize the Client

Create a PxOracle instance with your connection, API key, and ZK configuration. The compression flag enables Light Protocol compressed PDAs for proof storage. All parameters except connection and apiKey have sensible defaults. The zkConfig object is optional unless you need custom circuit parameters for advanced proving workflows.

import { PxOracle } from '@pxoracl/sdk';
import { Connection } from '@solana/web3.js';

const oracle = new PxOracle({
  connection: new Connection('https://api.mainnet-beta.solana.com'),
  apiKey: process.env.PXORACL_API_KEY,
  chain: 'solana',
  compression: true,
  zkConfig: {
    circuit: 'oracle_v2',
    hashFunction: 'sha256',
    privacyLevel: 'full',
    compressionEnabled: true,
    stateTreeDepth: 26,
  },
});

oracle.query

oracle.query(params: QueryParams): Promise<QueryResult>

Submits a single oracle query with optional ZK proof generation. This is the primary method for fetching verified data from the oracle network. When proof is set to true, the method generates a Groth16 zero-knowledge proof attesting to the correctness of the oracle response. The privacy parameter controls whether query inputs are encrypted via SHA-256 commitment before submission. Setting compression to true stores the proof in a Light Protocol compressed PDA, reducing on-chain storage cost by up to 1000x compared to a standard Solana account. The method handles the full pipeline internally: commitment generation, network submission, proof verification, and result parsing.

const result = await oracle.query({
  asset: 'So11111111111111111111111111111111111111112',
  dataType: 'price_feed',
  proof: true,
  privacy: 'full',
});

// result.verified   -> boolean
// result.value      -> number | string
// result.zkProof    -> string (Groth16 proof hash)
// result.riskScore  -> number (0-100)
// result.timestamp  -> number (unix ms)

oracle.subscribe

oracle.subscribe(params: SubscribeParams, cb: UpdateCallback): Subscription

Creates a WebSocket subscription for real-time oracle data updates. The callback fires at the configured interval with the latest data and proof validation status. Each update includes a sequence number for ordering guarantees. The subscription automatically reconnects with exponential backoff if the connection drops, starting at 1 second and maxing out at 30 seconds. Proof validation runs on every update when proof is true in the params. The subscription object exposes an unsubscribe method to cleanly close the connection and free resources.

const sub = oracle.subscribe({
  asset: 'TOKEN_MINT_ADDRESS',
  dataType: 'price_feed',
  interval: 5000,
  proof: true,
}, (update) => {
  console.log(update.value);
  console.log(update.proofValid);
  console.log(update.sequenceNumber);
});

// Auto-reconnects with exponential backoff
// sub.unsubscribe() to close

oracle.crossChain

oracle.crossChain(params: CrossChainParams): Promise<CrossChainResult>

Executes a cross-chain oracle query by routing through chain-specific bridge adapters. Currently supports Ethereum and BSC as source chains with Solana as the settlement layer. The method fetches data from the source chain, generates a storage proof against the source block header, bridges the result to Solana, and verifies the storage proof on-chain. When verifyStorageProof is true, the adapter checks the data against a Merkle Patricia Trie proof anchored to the source chain block hash. Bridge latency varies by source chain: Ethereum averages 12-15 seconds, BSC averages 3-5 seconds. The result includes the source block number for auditability.

const ethResult = await oracle.crossChain({
  sourceChain: 'ethereum',
  asset: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
  dataType: 'price_feed',
  proof: true,
  verifyStorageProof: true,
});

// ethResult.value              -> number
// ethResult.storageProofValid  -> boolean
// ethResult.bridgeLatency      -> number (ms)
// ethResult.sourceBlockNumber  -> number

Batch Query -- Portfolio Dashboard

Query up to 100 assets in a single call. Batch queries are cheaper than individual queries because proof generation is amortized across the batch. The SDK groups assets by chain and parallelizes bridge requests for cross-chain assets.

// Batch query up to 100 assets in a single call
const batch = await oracle.batchQuery([
  { asset: 'MINT_1', chain: 'solana', dataType: 'price_feed' },
  { asset: 'MINT_2', chain: 'solana', dataType: 'liquidity' },
  { asset: '0xA0b8...3f2E', chain: 'ethereum', dataType: 'price_feed' },
]);

for (const r of batch.results) {
  console.log(`${r.chain}/${r.asset}: ${r.verified ? 'OK' : 'FAIL'}`);
}

// batch.totalCost   -> number (in $PXCL)
// batch.proofCount  -> number
// batch.latency     -> number (ms)

Rust Integration -- On-Chain Program

The Rust SDK mirrors the TypeScript API surface with native Solana types. Use it for building Anchor programs that consume oracle data, backend services that aggregate oracle feeds, or any Rust application that needs verified on-chain data. The Rust SDK uses the same underlying RPC calls and proof format as the TypeScript SDK, so proofs are interchangeable between languages.

use pxoracl_sdk::{PxOracle, QueryParams, DataType};
use solana_sdk::pubkey::Pubkey;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let oracle = PxOracle::new()
        .rpc("https://api.mainnet-beta.solana.com")
        .api_key(std::env::var("PXORACL_API_KEY")?)
        .compression(true)
        .build()?;

    let result = oracle.query(QueryParams {
        asset: Pubkey::from_str("So111...1112")?,
        data_type: DataType::PriceFeed,
        proof: true,
        privacy: pxoracl_sdk::Privacy::Full,
    }).await?;

    println!("Verified: {}", result.verified);
    println!("Value: {}", result.value);
    println!("Proof: {}", result.zk_proof);
    Ok(())
}