// ExergyNet · Developer Documentation

B2B Integration
API Reference

Connect your biotech SaaS to ZK-verified pharmaceutical compute in four steps. ExergyNet separates data mass from cryptographic proof — heavy files stay in S3, mathematical truth settles on Base L2.

L0 Router Live Base Sepolia · LNES-04 (Testnet) ZK-STARK Verified USDC Settlement

01 The Sovereign Compute Pipeline

ExergyNet operates on one physical axiom: electricity cost is the only irreducible cost of computation. All other cloud pricing — corporate margins, hardware depreciation, profit extraction — is eliminated by routing work to a global swarm of prover nodes that compete on electricity price alone.

The network enforces a strict separation: heavy data (SDF/PDB files, docking pose outputs) lives in AWS S3. The mathematical proof that the computation was executed correctly is settled on Base L2 as a ZK-STARK receipt. Your FDA submission references the proof hash — not the raw data.

01
// Estimate
Query the Pricing Oracle

POST your file metadata to /api/v1/estimate. The L0 Router calculates the live wholesale USDC cost based on simulation type, molecular weight, and atom count. This is the raw compute cost — electricity + ZK-proof gas — with zero corporate markup. Apply your own SaaS multiplier to set your retail price.

02
// Stage
Upload the Payload

POST your .SDF, .PDB, .SMI, or .MOL2 file to /api/v1/compute/upload. The endpoint hashes the content with SHA-256, stores it to the S3 sump, and returns a deterministic blueprint_id. This is the data mass layer — it never touches the blockchain.

03
// Lock
Open the Escrow

Use @exergynet/agent-sdk to call openJob() on the LNES-04 smart contract. This locks only the wholesale USDC toll into escrow. Your retail capture from the end user happens in your own treasury before this step. The contract emits a JobOpened event that broadcasts the job to the global prover swarm.

04
// Retrieve
Poll for the ZK Receipt

Poll /api/l0/transactions?job_id={hex} until status: "ZK-STARK VERIFIED". The response contains proof_hash (the on-chain cryptographic proof) and result_s3_url (the docking pose output). Store the proof_hash as your FDA-compliant audit trail. The proof is immutable on Base L2.

02 Economic Architecture

The retail and wholesale capital flows are strictly decoupled. Your SaaS treasury and the ExergyNet escrow are separate financial rails. Never mix them.

User Pays
$25.00
Stripe / Web3 checkout
→ Your Treasury
You Escrow
$1.25
Wholesale toll only
→ LNES-04 Contract
Prover Earns
$0.37
30% of wholesale
→ Prover Wallet
// Critical: Surplus Agent Wallet Your backend must maintain a separate Surplus Agent Wallet on Base L2 funded with USDC for wholesale toll payments. This wallet is not your main treasury. It holds only the capital required for pending ExergyNet jobs. Configure it via MD_SURPLUS_AGENT_WALLET and MD_SURPLUS_AGENT_KEY environment variables.
Capital Flow Sequence
Pseudocode
// Step A: Retail capture (your domain — happens BEFORE ExergyNet)
retail_price = estimate.wholesale_usdc * YOUR_MARKUP_MULTIPLIER
charge_user(retail_price)  // Stripe, Web3 checkout — to YOUR treasury
// $23.75 profit stays in your treasury

// Step B: Wholesale escrow (ExergyNet domain)
await client.openJob(
    job_id_bytes,
    sha256_hash_bytes,
    estimate.wholesale_micro_usdc   // ONLY the wholesale amount
)
// $1.25 locked in LNES-04 escrow

// Step C: Tri-partite settlement (automatic)
// Siphon Daemon sees verified proof on L0 and triggers settleExergy()
// 30% ($0.37) → Prover's payment_address (electricity coverage)
// 70% ($0.88) → EDT Architect Vault (architect tax)

03 Quick Start

Full integration from a cold start. Assumes Node.js backend and a funded Base L2 surplus agent wallet.

JavaScript — Full Integration
import { ExergyNetClient } from "@exergynet/agent-sdk";
import fs from "fs";

// ── 1. Initialize SDK with your surplus agent wallet ──
const client = new ExergyNetClient({
  rpcUrl: "https://sepolia.base.org",
  contractAddress: "0x3241941beBE7D7f0c42097D8646DF50992B272FB",
  surplusAgentKey: process.env.MD_SURPLUS_AGENT_KEY,
  baseUrl: "https://explorer-api.exergynet.org",
});

async function runSimulation(filePath, simulationType) {
  // ── 2. Get wholesale cost estimate ──
  const fileBuffer = fs.readFileSync(filePath);
  const fileStat   = fs.statSync(filePath);

  const estimate = await fetch("https://explorer-api.exergynet.org/api/v1/estimate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      simulation_type: simulationType,
      blueprint_data: { file_size_bytes: fileStat.size, molecular_weight: 820, atom_count: 90 },
    }),
  }).then(r => r.json());

  // ── 3. Upload compound file ──
  const formData = new FormData();
  formData.append("file", new Blob([fileBuffer]), "compound.sdf");
  const upload = await fetch("https://explorer-api.exergynet.org/api/v1/compute/upload",
    { method: "POST", body: formData }).then(r => r.json());

  // ── 4. Lock wholesale toll in escrow ──
  const signature = await client.openJob(
    hexToBytes(upload.blueprint_id),
    hexToBytes(upload.sha256_hash),
    estimate.wholesale_usdc_micro_units
  );

  // ── 5. Poll for ZK-STARK proof ──
  const result = await pollForProof(upload.blueprint_id);
  console.log(`Proof: ${result.proof_hash}`);
  return result;
}

async function pollForProof(jobId, maxAttempts = 60, intervalMs = 15000) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(
      `https://explorer-api.exergynet.org/api/l0/transactions?job_id=${jobId}`
    ).then(r => r.json());
    if (res.status === "ZK-STARK VERIFIED") return res;
    if (res.status === "FAILED") throw new Error(`Job failed: ${res.error}`);
    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error("Proof timeout after 15 minutes");
}

04 Authentication

The ExergyNet L0 Router uses Ed25519 request signing. Every API call from your Surplus Agent Wallet must include a signature header derived from your Ed25519 private key.

X-Exergy-Wallet0xYOUR_SURPLUS_AGENT_EVM_ADDRESS
X-Exergy-Sig0xED25519_SIGNATURE_OF_REQUEST_BODY_HASH
X-Exergy-NonceUnix timestamp (must be within 60s of server time)
Python — Request Signing
import time, hashlib, os
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

def sign_request(body_json: str, private_key_hex: str) -> dict:
    nonce = str(int(time.time()))
    body_hash = hashlib.sha256((nonce + body_json).encode()).hexdigest()
    key_bytes = bytes.fromhex(private_key_hex.replace("0x", ""))
    private_key = Ed25519PrivateKey.from_private_bytes(key_bytes)
    signature = "0x" + private_key.sign(body_hash.encode()).hex()
    return {
        "X-Exergy-Wallet": os.environ["MD_SURPLUS_AGENT_WALLET"],
        "X-Exergy-Sig": signature,
        "X-Exergy-Nonce": nonce,
        "Content-Type": "application/json",
    }

05 Compute Vectors

Select the correct simulation_type string for your workload. Compute class determines which ELF circuit is used and the base USDC toll multiplier.

SimulationString IDClassZK CircuitMultiplier
Temporal ADMETTEMPORAL_ADMETLIGHTBCX-002-v11.0x
MDC Logic / FDA AuditMDC_LOGICLIGHTBCX-004-v1.21.0x
Molecular DynamicsMOLECULAR_DYNAMICSMEDIUMBCX-003-v13.0x
Virtual ScreeningVIRTUAL_SCREENINGMEDIUMBCX-001-v13.0x
Encrypted ScreeningENCRYPTED_SCREENINGHEAVYBCX-001-v110.0x
// Density Penalty Molecules exceeding 800 MW or 80 atoms trigger an automatic 1.6x density penalty multiplier applied on top of the base multiplier. A HEAVY class job with a 900 MW ligand costs 10.0 × 1.6 = 16.0x base toll. Include molecular_weight and atom_count in your estimate payload to get accurate pricing before opening escrow.

06 API Endpoints

POST https://explorer-api.exergynet.org/api/v1/estimate
Pricing Oracle. Returns the live wholesale USDC cost to compute the job. Call this before charging your user. The response wholesale_usdc_micro_units is the exact amount to pass to openJob().
Request Payload
JSON
{
  "simulation_type": "ENCRYPTED_SCREENING",
  "blueprint_data": {
    "file_size_bytes": 5242880,
    "molecular_weight": 820,  // > 800 triggers 1.6x density penalty
    "atom_count": 90           // > 80 also triggers density penalty
  }
}
200 OK
JSON Response
{
  "wholesale_usdc_micro_units": 19200000,  // = $19.20 USDC
  "compute_class": "HEAVY",
  "network": "base-sepolia",
  "elf_circuit": "BCX-001-v1",
  "density_penalty_applied": true,
  "base_multiplier": 10.0,
  "density_multiplier": 1.6,
  "estimated_proof_time_minutes": 12
}
POST https://explorer-api.exergynet.org/api/v1/compute/upload
Payload staging. Accepts multipart/form-data. SHA-256 hashes the content, stores to S3 sump, returns a deterministic blueprint_id. Accepted: .sdf .pdb .smi .mol2 .json. Max 512 MB.
Request — multipart/form-data
cURL
curl -X POST https://explorer-api.exergynet.org/api/v1/compute/upload \
  -H "X-Exergy-Wallet: 0xYOUR_WALLET" \
  -H "X-Exergy-Sig: 0xYOUR_SIGNATURE" \
  -H "X-Exergy-Nonce: 1716381600" \
  -F "file=@compound_library.sdf"
200 OK
JSON Response
{
  "status": "STAGED",
  "blueprint_id": "UPLOAD-31EE488C",
  "sha256_hash": "31ee488c13189e5fff18...",
  "file_size": 5242880,
  "filename": "compound_library.sdf",
  "format": "SDF"
}
POST https://explorer-api.exergynet.org/api/v1/jobs
Job broadcast. Posts the job to the L0 Router for pickup by the prover swarm. For most integrations, call client.openJob() from the SDK instead — it combines the smart contract escrow and this broadcast in one atomic operation.
Request Payload
JSON
{
  "job_id": "0xJOB_HEX_ID",
  "blueprint_id": "UPLOAD-31EE488C",
  "simulation_type": "ENCRYPTED_SCREENING",
  "compute_class": "HEAVY",
  "escrow_amount_micro_usdc": 19200000,
  "sha256_hash": "31ee488c13189e5fff18...",
  "requester_wallet": "0xYOUR_SURPLUS_AGENT_WALLET",
  "elf_circuit": "BCX-001-v1"
}
GET https://explorer-api.exergynet.org/api/l0/transactions?job_id={job_id_hex}
Proof retrieval. Poll at 15-second intervals until status returns ZK-STARK VERIFIED. Expected wait: 3–15 minutes depending on compute class and current swarm load.
Pending
JSON — Pending
{
  "job_id_hex": "0xJOB_HEX_ID",
  "status": "COMPUTING",
  "miner_id": "Node_DE_Alpha_07",
  "elapsed_seconds": 187
}
Verified
JSON — Verified
{
  "job_id_hex": "0xJOB_HEX_ID",
  "status": "ZK-STARK VERIFIED",
  "proof_hash": "0x874505af4b4fbd...",    // Store for FDA audit trail
  "result_s3_url": "https://exergynet-results.s3.amazonaws.com/JOB_123.json",
  "miner_id": "Node_DE_Alpha_07",
  "payment_address": "0x71C...49b",
  "elapsed_seconds": 743
}
// FDA Compliance Store proof_hash in your database alongside the simulation result. This is your immutable on-chain attestation. It can be verified by any party — including an FDA reviewer — by querying the LNES-04 Base L2 contract.
GET https://explorer-api.exergynet.org/api/v1/jobs/{job_id}/proof
Returns the full Groth16/STARK receipt for a completed job. Use this to retrieve the raw proof bytes for on-chain verification or inclusion in a regulatory submission package.

07 Agent SDK

The @exergynet/agent-sdk handles Ed25519 signing, Base L2 transaction construction, and smart contract interaction. It is the recommended integration path for production SaaS deployments.

npm
npm install @exergynet/agent-sdk
openJob()

Atomic operation: constructs the Base L2 transaction, signs with your surplus agent wallet, broadcasts the openJob smart contract call, and emits the job to the prover swarm in a single call.

TypeScript
const signature: string = await client.openJob(
  jobIdBytes:  Uint8Array,  // 32-byte job identifier
  sha256Bytes: Uint8Array,  // SHA-256 hash of the uploaded file
  microUsdc:   number,     // from /estimate endpoint
);
// Returns: Base L2 transaction signature
// Effect:  Locks USDC in LNES-04 escrow
// Event:   JobOpened emitted → broadcast to prover swarm
settleExergy() — Siphon Daemon Only

Called automatically by the ExergyNet Siphon Daemon when a verified proof is detected on L0. Do not call this from your integration. Documented here for transparency on the settlement flow.

Solidity — LNES-04 Contract Interface
// LNES-04 (Base Sepolia testnet): 0x3241941beBE7D7f0c42097D8646DF50992B272FB

function settleExergy(
    bytes32 jobId,
    address proverPaymentAddress,
    bytes32 proofHash
) external onlySiphonDaemon {
    uint256 escrow = escrows[jobId];
    uint256 proverYield = (escrow * 30) / 100;  // 30% → prover
    USDC.transfer(proverPaymentAddress, proverYield);
    USDC.transfer(EDT_VAULT, escrow - proverYield); // 70% → architect vault
    emit ExergySettled(jobId, proverPaymentAddress, proverYield);
}

08 Prover Network

ExergyNet is a permissionless DePIN. Any machine globally running moleculogic_prover.py can join the swarm, claim jobs, compute ZK-STARK proofs, and earn 30% USDC yield per verified computation.

✕ Wrong — Centralized
# Hardcoded — breaks the swarm
MINER_ID = "Moleculogic_SEI_L0"
PAYMENT_ADDRESS = ""  # unreported!
✓ Correct — Decentralized
# Loaded from operator's .env
MINER_ID = os.environ["MINER_ID"]
PAYMENT_ADDRESS = os.environ["PAYMENT_ADDRESS"]
Prover Setup
.env.example
# ExergyNet Prover Configuration — DO NOT commit to version control

MINER_ID=Node_YOURNAME_01
PAYMENT_ADDRESS=0xYOUR_EVM_WALLET   # Base L2 wallet for 30% USDC yield
PROVER_PRIVATE_KEY=0xYOUR_ED25519_PRIVATE_KEY
EXERGYNET_L0_URL=https://explorer-api.exergynet.org
POLL_INTERVAL_SECONDS=30
MAX_CONCURRENT_JOBS=2
Shell
git clone https://github.com/exergynet/moleculogic-prover
cd moleculogic-prover
cp .env.example .env   # edit with your wallet
pip install -r requirements.txt
python3 moleculogic_prover.py
Payout Structure
Compute ClassWholesale TollProver Yield (30%)Est. GPU Time
LIGHT$2.00 USDC$0.60 USDC5–15 min
MEDIUM$8.00 USDC$2.40 USDC15–45 min
HEAVY$25.00 USDC$7.50 USDC45–120 min

09 Error Codes

HTTPCodeMessageResolution
400INVALID_FORMATUnsupported file formatUse .sdf, .pdb, .smi, .mol2, or .json
400DENSITY_OVERFLOWMW or atom count exceeds HEAVY class limitFragment molecule or contact for custom pricing
401INVALID_SIGNATUREEd25519 signature verification failedCheck nonce is within 60s, verify key pair matches wallet
402INSUFFICIENT_ESCROWUSDC in escrow below estimateRe-query /estimate and use returned micro_units value
404JOB_NOT_FOUNDJob ID not found on L0 RouterVerify job_id_hex format, confirm openJob transaction confirmed
413PAYLOAD_TOO_LARGEFile exceeds 512 MB upload limitSplit compound library into batches under 512 MB
503SWARM_UNAVAILABLENo provers available for compute classRetry after 60s; consider downgrading compute class

10 Smart Contracts

LNES-04 Contract (Sepolia — integrate here)0x3241941beBE7D7f0c42097D8646DF50992B272FB
NetworkBase Sepolia (Chain ID: 84532) — recommended integration target
Settlement TokenUSDC (testnet) — 0x036CbD53842c5426634e7929541eC2318f3dCF7e
LNES-04 Contract (Base Mainnet)0x5cfE075149776f4b3cca07a27D4fd85A60BA5e3f — deployed, not yet the recommended default
Key EventsJobOpened(jobId, requester, microUsdc) · ExergySettled(jobId, prover, yield, tax)

11 AlphaFold Bridge

ExergyNet's ENCRYPTED_SCREENING and VIRTUAL_SCREENING compute vectors are the execution layer for AlphaFold 3 structural outputs. AlphaFold maps the 3D target lock. ExergyNet runs the programmable key.

// The AlphaFold 3 Gap AlphaFold 3 excels at static spatial geometry but stops at temporal causal logic — it cannot simulate how a molecule behaves dynamically under fluctuating pH, ROS, or enzymatic concentrations. Upload your AlphaFold .pdb output to /api/v1/compute/upload, then call /api/v1/alphafold/analyze to detect binding pocket coordinates and run ADMET + contradiction screening before dispatching to the ExergyNet docking swarm.
AlphaFold → ExergyNet Pipeline
# 1. Export .pdb from alphafoldserver.com
# 2. Upload to Metaldrug / ExergyNet
upload = requests.post(
    "https://platform.metaldrug.com/api/v1/compute/upload",
    files={"file": open("TP53_alphafold.pdb", "rb")},
)
blueprint_id = upload.json()["blueprint_id"]

# 3. Analyze binding pocket + contradiction check
analysis = requests.post(
    "https://platform.metaldrug.com/api/v1/alphafold/analyze",
    json={"blueprint_id": blueprint_id, "run_admet": True,
          "candidate_smiles": "CC1=CC=C(C=C1)S(=O)(=O)N"}
)
viable = analysis.json()["contradictions"]["viable"]

if viable:
    await client.openJob(job_id, sha256, micro_usdc)
else:
    print(analysis.json()["contradictions"]["contradiction_flags"])

12 Portal Platform Services

Everything above this section is the Explorer / Moleculogic ZK-compute marketplace — Ed25519 wallet-signed, escrow-settled. ExergyNet also runs a separate SaaS platform on portal.exergynet.org: inference, encrypted data-at-rest queries, structured extraction, an agent MCP bridge, external-site zkTLS witnessing, and a token capital loop. These services use simple Bearer-token auth, not wallet signatures — don't mix the two credential systems.

// Getting a key Generate an EXERGYNET_API_KEY (format sk-exergy-...) at portal.exergynet.org/dashboard/keys. Every request below needs Authorization: Bearer <key>.
// Status AERIS Witness is fully real — Groth16-sealed on Base Sepolia. Vault ZK Query currently returns a SHA-256 receipt in place of a full RISC Zero proof while that circuit is finished. Treat all portal services as testnet-stage.

Loading live service list…

// TypeScript / Python examples Full TypeScript and Python snippets for every service above, plus live key generation and rotation, are available at portal.exergynet.org/dashboard/keys once you're signed in.
Ready to integrate?

Your first job is on Base Sepolia testnet — no real USDC required. Connect your surplus agent wallet, upload a compound file, and receive a ZK-STARK proof within 15 minutes.