Client                                  Agent
  │                                       │
  │  1. Discover pricing                  │  (read the agent's PDA)
  │  2. Create escrow + deposit funds     │  (one Solana TX)
  │  3. Call agent with x402 headers      │  (standard HTTP request)
  │  4. Agent serves the request          │  (off-chain computation)
  │  5. Agent settles on-chain            │  (claims payment from escrow)
  │  6. Client verifies settlement TX     │  (on-chain, auditable)

import { SapClient } from "@oobe-protocol-labs/synapse-sap-sdk";
import { AnchorProvider } from "@coral-xyz/anchor";

const client = SapClient.from(AnchorProvider.env());

// estimateCost reads the agent's pricing from on-chain data
// and applies volume curve discounts if they exist.
const estimate = await client.x402.estimateCost(
  agentWallet,   // PublicKey: the agent you want to call
  100,           // number:    how many calls to estimate
);

console.log(estimate.totalCost.toString());            // BN: total lamports needed
console.log(estimate.effectivePricePerCall.toString()); // BN: weighted avg price
console.log(estimate.hasVolumeCurve);                  // boolean: applies discounts?
console.log(estimate.tiers);                           // per-tier breakdown array

const ctx = await client.x402.preparePayment(agentWallet, {
  pricePerCall: 1_000,       // base price in lamports per API call
  maxCalls: 500,             // maximum calls allowed (0 = unlimited)
  deposit: 500_000,          // lamports to deposit upfront into the escrow
  expiresAt: 0,              // Unix timestamp for escrow expiry (0 = never expires)
  volumeCurve: [             // optional: tiered pricing (max 5 breakpoints)
    { afterCalls: 100, pricePerCall: 800 },  // after 100 calls: 800 lamports each
    { afterCalls: 300, pricePerCall: 600 },  // after 300 calls: 600 lamports each
  ],
  // tokenMint: null,        // optional: SPL token mint (null = native SOL)
  // tokenDecimals: 9,       // optional: token decimals (default: 9 for SOL)
});

console.log("Escrow PDA:", ctx.escrowPda.toBase58());
console.log("TX:", ctx.txSignature);

// buildPaymentHeaders turns the PaymentContext into HTTP headers.
// Pass these with every API request to the agent's x402 endpoint.
const headers = client.x402.buildPaymentHeaders(
  ctx,                         // PaymentContext from preparePayment()
  // { network: "mainnet-beta" }  // optional: defaults to "mainnet-beta"
);

const response = await fetch(agentEndpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    ...headers,                // merges all X-Payment-* headers
  },
  body: JSON.stringify({ prompt: "Analyze SOL/USDC liquidity" }),
});

// settle() is called by the AGENT after serving requests.
// The agent's wallet must be the escrow's agentWallet.
const receipt = await client.x402.settle(
  depositorWallet,             // PublicKey: the client who funded the escrow
  5,                           // number:    how many calls to settle
  "service-data-v1",           // string:    service proof (auto-hashed to SHA-256)
);

console.log(receipt.callsSettled);         // 5
console.log(receipt.amount.toString());    // lamports transferred to agent
console.log(receipt.txSignature);          // Solana TX signature
console.log(receipt.serviceHash);          // number[] (32 bytes)

// settleBatch processes up to 10 settlements in one Solana TX.
// More gas-efficient than calling settle() 10 times.
const batch = await client.x402.settleBatch(
  depositorWallet,             // PublicKey: the client who funded the escrow
  [
    { calls: 3, serviceData: "batch-1-data" }, // 3 calls from first batch
    { calls: 7, serviceData: "batch-2-data" }, // 7 calls from second batch
  ],  // max 10 entries per batch (LIMITS.MAX_BATCH_SETTLEMENTS)
);

console.log(batch.totalCalls);       // 10
console.log(batch.totalAmount.toString()); // total lamports
console.log(batch.settlementCount);  // 2

// getBalance returns null if no escrow exists for this agent+depositor pair.
const balance = await client.x402.getBalance(
  agentWallet,     // PublicKey: the agent's wallet
  // depositor,    // optional: defaults to the connected wallet
);

if (balance) {
  console.log(balance.balance.toString());     // BN: current lamport balance
  console.log(balance.callsRemaining);         // number: maxCalls - settled (Infinity if unlimited)
  console.log(balance.isExpired);              // boolean: has the escrow expired?
  console.log(balance.affordableCalls);        // number: calls affordable at current price
  console.log(balance.totalDeposited.toString()); // BN: cumulative deposits
  console.log(balance.totalSettled.toString());   // BN: cumulative settlements
}

interface VolumeCurveBreakpoint {
  afterCalls: number;
  pricePerCall: BN;
}

const tokenMint = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"); // USDC

await client.escrow.create(agentWallet, {
  pricePerCall: new BN(1_000),
  maxCalls: new BN(1000),
  initialDeposit: new BN(1_000_000),
  tokenMint,
  tokenDecimals: 6,
}, splAccounts);

Agent proposes settlement → Pending state created
  ↓
Depositor reviews within window
  ├── No dispute → Agent calls finalize() → Funds released
  └── Dispute filed → Arbiter resolves
       ├── DepositorWins → Funds returned
       ├── AgentWins → Funds released to agent
       └── AutoReleased → Window expired, funds auto-released

import { deriveEscrowV2, derivePendingSettlement, deriveDispute } from "@oobe-protocol-labs/synapse-sap-sdk/pda";

const [escrowV2Pda] = deriveEscrowV2(agentPda, depositorWallet, nonce);
const [pendingPda] = derivePendingSettlement(escrowV2Pda, settlementNonce);
const [disputePda] = deriveDispute(pendingPda);

await client.escrowV2.migrateFromV1(agentWallet);

await client.staking.initStake(agentWallet, new BN(1_000_000_000));
await client.staking.deposit(agentWallet, new BN(500_000_000));
await client.staking.requestUnstake(agentWallet, new BN(500_000_000));
// ... wait ~7 days ...
await client.staking.completeUnstake(agentWallet);

import { BillingInterval } from "@oobe-protocol-labs/synapse-sap-sdk";

await client.subscription.create(agentWallet, {
  subId: 1,
  amount: new BN(100_000),
  interval: BillingInterval.Monthly,
});