@flying-whale/gate-sdk

EPC-1: Execution Precondition Protocol — Official TypeScript SDK

The protocol every execution system speaks before capital moves.

EPC-1 is a deterministic pre-execution verification standard. Before any swap, trade, or DeFi operation executes, call epcEvaluate() — get a probability score, a policy decision, and a cryptographically anchored certificate.

Owner: Flying Whale | zaghmout.btc | ERC-8004 #54
API: https://fwgate.to
Standard: EPC-1 v1.2 | FW_GATE_v1.0

Installation

npm install @flying-whale/gate-sdk

EPC-1 Quick Start

import { createClient } from '@flying-whale/gate-sdk';

const gate = createClient({ callerId: 'my-dex-router' });

// --- Pattern 1: Guard (throws if blocked) ---
await gate.epcGuard({ from: 'STX', to: 'ALEX', amount: 1000 });
// if execution is blocked → throws EpcBlockedError
// if execution is viable → continues silently

// --- Pattern 2: Check (boolean) ---
const ok = await gate.canExecute({ from: 'STX', to: 'ALEX', amount: 1000 });
if (!ok) return;  // silently skip

// --- Pattern 3: Full result ---
const result = await gate.epcEvaluate({ from: 'STX', to: 'ALEX', amount: 1000 });
console.log(result.verdict);           // 'viable' | 'degraded' | 'non_executable' | 'unknown'
console.log(result.execution_allowed); // true | false
console.log(result.p_success);         // 0.00 → 1.00  (probability of success)
console.log(result.confidence);        // 0.00 → 1.00  (model confidence)
console.log(result.latency_ms);        // evaluation latency
console.log(result.risk.slippage_pct); // slippage risk %
console.log(result.risk.liquidity_score); // 0 = dry, 1 = deep
console.log(result.risk.route_validity);  // 'valid' | 'degraded' | 'broken'
console.log(result.policy.decision);      // 'EXECUTE' | 'WARN' | 'BLOCK'
console.log(result.cert_id);              // 'fw-s-xxxxxxxx'
console.log(result.chain_anchor);         // 'SP322...fw-epc-verifier-v1'

DEX Integration (3 lines)

import { createClient, EpcBlockedError } from '@flying-whale/gate-sdk';
const gate = createClient({ callerId: 'my-dex' });

async function swap(from: string, to: string, amount: number) {
  await gate.epcGuard({ from, to, amount }); // ← add this before any swap
  return executeSwap(from, to, amount);
}

If the route is blocked, epcGuard() throws EpcBlockedError with the full EPC-1 result attached.

AI Agent Integration

// In any agent pre-execution hook:
const canRun = await gate.canExecute({ from: 'WHALE', to: 'sBTC', amount: 50000 });
if (!canRun) {
  agent.log('EPC-1 blocked execution — skipping');
  return;
}
await agent.execute();

Smart Router Filter

// Filter routes before submission:
const routes = await getRoutes(from, to);
const viable = await Promise.all(
  routes.map(r => gate.canExecute({ from: r.from, to: r.to, amount }))
);
const safeRoutes = routes.filter((_, i) => viable[i]);

Batch Evaluation (up to 20 routes)

const results = await gate.epcBatch([
  { from: 'STX', to: 'ALEX', amount: 1000 },
  { from: 'STX', to: 'sBTC', amount: 500 },
  { from: 'WHALE', to: 'wSTX', amount: 10000 },
]);
// results: Epc1Response[]  — all evaluated in parallel server-side

Free Preview (no payment)

const preview = await gate.epcPreview({ from: 'STX', to: 'ALEX', amount: 1000 });
// Returns verdict + risk without cert, cert_id, or chain anchor
// Use for UI previews and pre-flight checks

Feedback Loop

After execution, report the outcome to improve model accuracy:

await gate.epcFeedback(result.cert_id, {
  tx_id:               '0xabc123...',
  success:             true,
  actual_slippage_pct: 2.1,
});
// Model calibration improves with each feedback signal

Error Handling

import { EpcBlockedError } from '@flying-whale/gate-sdk';

try {
  await gate.epcGuard({ from: 'WHALE', to: 'sBTC', amount: 1000 });
} catch (err) {
  if (err instanceof EpcBlockedError) {
    console.log(err.result.verdict);          // 'non_executable'
    console.log(err.result.p_success);        // 0.04
    console.log(err.result.policy.decision);  // 'BLOCK'
    console.log(err.result.risk.route_validity); // 'broken'
  }
}

System Health & Observability

const health = await gate.epcHealth();
// { status: 'healthy', components: { oracle, routing, signer }, cache: { hit_rate } }

EPC-1 Response Schema

interface Epc1Response {
  standard:          'EPC-1';
  version:           string;           // '1.2'
  cert_id:           string;           // 'fw-s-xxxxxxxx'
  verdict:           'viable' | 'degraded' | 'non_executable' | 'unknown';
  execution_allowed: boolean;
  p_success:         number;           // 0.00 → 1.00
  confidence:        number;           // 0.00 → 1.00
  latency_ms:        number;
  risk: {
    slippage_pct:    number;
    liquidity_score: number;           // 0 = dry, 1 = deep
    route_validity:  'valid' | 'degraded' | 'broken';
  };
  system: {
    oracle_ok:    boolean;
    routing_ok:   boolean;
    signer_ok:    boolean;
  };
  policy: {
    decision:          'EXECUTE' | 'WARN' | 'BLOCK';
    execution_allowed: boolean;
    rule_triggered:    string | null;
  };
  state_root:    string;               // SHA-256 of cert payload
  chain_anchor:  string;               // 'SP322...fw-epc-verifier-v1'
  chain_log:     string;               // 'SP322...fw-execution-log-v1'
  proof_url:     string;               // 'https://fwgate.to/proof/fw-s-...'
  issued_at:     string;               // ISO 8601
  cache: {
    hit:       boolean;
    cached_at: number | null;
  };
}

On-Chain Contracts (Stacks mainnet)

Every evaluation anchors on-chain via three deployed contracts at block 7693249:

| Contract | Address | |---|---| | fw-epc-verifier-v1 | SP322ZK4VXT3KGDT9YQANN9R28SCT02MZ97Y24BRW | | fw-execution-log-v1 | SP322ZK4VXT3KGDT9YQANN9R28SCT02MZ97Y24BRW | | fw-root-registry-v1 | SP322ZK4VXT3KGDT9YQANN9R28SCT02MZ97Y24BRW |

Every cert_id maps to a store-cert call on fw-epc-verifier-v1.
Every feedback with tx_id calls log-execution on fw-execution-log-v1.

Free Endpoints (no payment required)

| Endpoint | Description | |---|---| | POST /epc/v1/preview | Unsigned preview — verdict + risk, no cert | | GET /gate/dashboard | Aggregate metrics: scans, model accuracy, Merkle, on-chain | | GET /gate/health | System component liveness | | GET /gate/model-accuracy | Model calibration transparency | | GET /gate/merkle | Current Merkle batch snapshot | | GET /gate/merkle/:cert_hash | Inclusion proof for a cert |

TypeScript Support

Full type declarations shipped — no @types/ package needed.

import type {
  Epc1Response,
  Epc1Risk,
  Epc1System,
  Epc1Policy,
  EpcBlockedError,
} from '@flying-whale/gate-sdk';

Legal

EPC-1 provides pre-execution analysis only — not financial advice. All execution decisions remain the responsibility of the calling system.

Flying Whale Proprietary License v3.0 — Agreement-First Policy.
Copyright 2026 Flying Whale | zaghmout.btc | ERC-8004 #54