# ConsensusAPI Whitepaper **Version:** 0.4 — Engineering status paper **Published:** 27 September 2026 **Status:** Project and architecture description; not a token-sale offer ## Important status notice ConsensusAPI is an early software project. The public website and API health/model-discovery endpoints are deployed. Wallet sign-in, individual API-key issuance, provider-key management, and a ledger implementation are present in the application. Paid job submission and CNS deposits remain disabled because no CNS mint, treasury, or verified pricing configuration is published. No CNS sale contract, sale price, supply, allocation, vesting schedule, or launch date is published in this paper. A proposed design is not a deployed feature. This paper describes engineering goals and the status known on its publication date. It does not offer or solicit tokens, promise returns, or represent that any token has been issued. Only sale information published with a verified on-chain contract and final legal terms may be relied on for a future sale. ## 1. Summary ConsensusAPI's objective is to provide one API through which software can submit AI tasks while keeping provider integrations replaceable. The proposed system separates off-chain request planning and execution from optional on-chain settlement. Providers connect through a normalized adapter interface; a router can select an eligible provider based on task capability, limits, availability, quality, latency, and price. The deployed prototype includes a TypeScript/Fastify API, asynchronous text-job lifecycle, a PostgreSQL job store, idempotency support, Solana wallet challenge verification, per-wallet API keys, and an OpenAI-compatible provider adapter. Provider credentials can be validated and encrypted under a server-held key. CNS billing is gated until the project configures an existing token mint, treasury destination, finalized-chain RPC, and published input/output rates. The prototype does not perform multi-provider consensus, media generation, a token sale, or on-chain settlement. ## 2. Problem and design goals AI model services expose different APIs, capability descriptions, limits, usage reports, and pricing formats. Applications that integrate each service directly must maintain provider-specific code and policies. ConsensusAPI is designed to provide: - A stable, model-independent request lifecycle. - A common provider adapter contract. - Capability- and constraint-based provider selection. - Explicit cost estimates, customer caps, usage receipts, and accounting. - Optional CNS settlement without placing prompts or model execution on-chain. These are design goals. Features are only available when implemented and explicitly shown as active in the product. ## 3. System architecture ```text Client → API authentication → Request validation → Job planner → Provider eligibility/router → Provider adapter or node → Usage verification → Cost/ledger services → Result and receipt → Optional batched Solana settlement ``` The public API is intended to remain independent of particular model vendors. Prompts, outputs, credentials, task plans, routing decisions, and detailed usage records belong off-chain. A Solana program, if built and audited, would handle only token custody and settlement state necessary for those operations. ### Current implementation - Public `GET /health` and `GET /v1/models` endpoints. - Asynchronous job submission and polling code in the application. - PostgreSQL-backed job and idempotency records. - An OpenAI-compatible text adapter in source. - Solana wallet sign-in using short-lived, one-use signed challenges. - Per-wallet API keys stored as hashes and shown only at issue/rotation. - Customer provider-key encryption and model discovery. - Atomic CNS ledger reservation/debit/release and finalized SPL deposit verification code, gated while token and price configuration are absent. - HTTPS website and API routing. - Job submission remains disabled until verified CNS funding and pricing configuration are available. No other provider, modality, token, sale contract, or settlement program is claimed to be live. ## 4. Request lifecycle The target lifecycle is: 1. Authenticate the customer and validate the request and idempotency key. 2. Analyze the request and, where required, produce a bounded task graph. 3. Filter providers by capability, context/input/output limits, availability, and customer constraints. 4. Estimate a maximum charge and reserve customer funds before paid execution. 5. Execute bounded tasks with explicit timeouts, retries, and cancellation behavior. 6. Verify reported usage against versioned provider pricing and stored request metadata. 7. Record actual charges and provider payables in an append-only ledger. 8. Release unused reservation and return a usage receipt. The financial code is gated in the deployed environment. Jobs are not accepted until the CNS mint/treasury and token-unit rate configuration are set. No production balances exist before a finalized transfer to the configured destination is independently verified. ## 5. Provider adapter and routing model An adapter normalizes model discovery, capability metadata, pricing, availability, cost estimates, execution, usage, cancellation, and health checks. A descriptor should include supported modality, context and input/output limits, pricing unit, and model identifier. Provider-specific error bodies and credentials must not be returned to customers. Eligibility is a hard filter: a provider that cannot satisfy the task's required capabilities, limits, or configured spending cap is not selected. Ranking among eligible providers may consider capability fit, context fit, reliability, historical quality, capacity, latency, price, and failure rate. Selection weights and provider claims need explicit verification; a large context window alone is not evidence of superior quality. The current code contains one OpenAI-compatible text adapter. Customers may connect their own credential from the dashboard; it is stored encrypted and used only for that wallet's requests. Image, vision, video, animation, audio, multi-provider routing, and independent consensus are future work. ## 6. Jobs, usage, and accounting Jobs use explicit states (`queued`, `running`, `succeeded`, `failed`) and idempotency controls. PostgreSQL stores job state. If a process restarts during an external provider call, the implementation marks the job interrupted rather than automatically replaying it, because replay could duplicate provider charges. The CNS customer ledger uses integer base units and append-only records for verified deposits, reservations, charges, and releases. Customer balances are divided into available, reserved, and spent amounts. Provider earnings and on-chain provider settlement are not implemented. Ledger invariants include: - Reservations cannot exceed available balance. - A charge cannot exceed its approved reservation or cap. - Unused reservation is released once. - Provider payable plus protocol fee reconciles to the customer charge. - A settlement or claim cannot be paid twice. No CNS mint, funded customer balance, deposit, charge, or settlement feature is active in production. The deposit verifier and ledger code are disabled because the token mint, treasury, decimals, and input/output rates have not been approved or published. ## 7. Proposed CNS and Solana layer The architecture proposes CNS as a utility asset for service payments and provider rewards, with Solana as a candidate settlement network. The proposed on-chain layer could use an SPL Token mint, program-derived vault authority, deposit/withdraw instructions, and batched provider settlements. Larger settlement batches could use Merkle-root claims to avoid a transfer for every API call. These statements describe a proposal only. There is currently no published CNS mint address, token program, vault, sale contract, settlement program, audit, or supported sale network. No deposits or purchases are accepted. Token supply, allocation, decimals, vesting, fees, governance, and sale terms remain undecided. Before any CNS transaction is enabled, the project must publish the authoritative mint and program addresses, token parameters, audited source, wallet flows, pricing, custody controls, pause/admin authorities, final sale terms, and appropriate legal disclosures. On-chain transactions must be tested on Devnet and independently reviewed before any Mainnet use. ## 8. Credentials and privacy Provider API keys remain off-chain and are not included in public source, job results, or blockchain state. Customer provider keys are validated against the provider model endpoint, encrypted with AES-256-GCM using a server-held encryption key, and scoped to the wallet that supplied them. The browser never receives a saved provider key back. Wallet authentication uses a short-lived, single-use challenge whose exact message is verified before issuing an API credential. API keys are shown once, stored as hashes, revocable, and rotatable; dashboard sessions are also stored as hashes and expire. Prompts and outputs may contain personal or confidential data. Retention, deletion, data-processing terms, provider data handling, backup policies, and jurisdictional requirements must be published before broad customer onboarding. ## 9. Risks and limitations The project depends on third-party provider availability, accurate pricing and usage reporting, reliable asynchronous processing, secure credential management, and correct accounting. A future token system additionally introduces smart-contract, custody, oracle/indexing, key-management, liquidity, regulatory, and operational risks. Provider-reported quality or usage is not inherently trustless. A ledger entry does not prove a token deposit unless it is tied to independently verified chain data. The current deployment is a technical preview, not a production billing system or investment product. It has no published independent audit, final token terms, or active token sale. ## 10. Development sequence and status | Workstream | Status | |---|---| | Public website and HTTPS | Deployed | | Health and model discovery | Deployed | | Async text-job prototype and PostgreSQL persistence | Deployed in source/host; customer submissions gated | | Customer wallet authentication and individual API keys | Implemented; gated by signed wallet challenge | | Customer-owned provider-key management | Implemented; server encryption key required | | CNS deposit verification and atomic usage ledger | Implemented in code; disabled until verified token/pricing configuration | | Final CNS economics and presale terms | Not published | | CNS mint, audited Solana program, and settlement | Not deployed | | Additional model/media providers | Not active | ## 11. Frequently asked questions ### Can I use the API for jobs now? Health and model discovery are public. A customer can connect a Solana wallet, receive an individual API key, and save an OpenAI-compatible provider credential in the dashboard. Paid job submission remains gated until verified CNS deposit and pricing configuration is active. ### How do I connect my provider account? After wallet sign-in, use the Dashboard to submit an OpenAI-compatible provider API key. The server checks the credential by requesting its model list, encrypts it at rest, and scopes it to the connected wallet. The secret is not returned after it is saved. Job execution remains gated until CNS billing is configured. ### Is CNS a live token, and can I buy it? No. No CNS mint or sale contract is published, and no sale is open. There is no verified sale price, allocation, vesting schedule, or purchase network. ### Which blockchain will CNS use? Solana is the proposed settlement target in the architecture. No CNS token or ConsensusAPI settlement program is deployed, so there is no supported CNS transaction network today. ### What does CNS do? Payments and provider rewards are proposed utility concepts. They are not enabled, and final token rights and parameters have not been published. ### Does ConsensusAPI support images, audio, video, or multiple models today? The current adapter prototype is text-oriented and OpenAI-compatible. A customer can inspect the model IDs returned by their saved provider credential. Additional providers, media capabilities, and multi-provider routing are planned but not live. ### Has the project or token contract been audited? No independent security audit is published for a CNS token or settlement contract. No token or settlement contract has been deployed. ### Where can I verify future sale details? Only use the official ConsensusAPI site and verify any future contract and token addresses against independently published, signed project documentation. This paper does not contain sale instructions. --- **ConsensusAPI — One API. All AI.** This paper is an engineering overview and status statement. Material project changes should be reflected in a dated revision.