NovaPilot Docs
One wallet. Every AI model. Any API.
Deposit USDC once, then use Claude, GPT, Gemini, and dozens of other models from a single balance — billed per token, no subscriptions, no separate accounts. Publish or consume any third-party API through the same wallet on the NovaPilot Marketplace.
Showing the everyday walkthrough — deposit, chat, and track spend.
Overview
What is NovaPilot?
NovaPilot is a Web3 AI API aggregation platform built on the Circle Arc network. Deposit USDC into your own Circle-managed wallet and use that single balance to call Anthropic, OpenAI, Google, and OpenRouter models — metered per token and deducted automatically.
On top of AI access, NovaPilot runs an open API Marketplace: any developer can publish an existing HTTP API and earn USDC per call, and any developer can subscribe to those APIs and pay per call from the same balance — no separate merchant account, no 30-day payout hold.
You don't need any prior crypto experience. Sign in like any other app, and NovaPilot handles the wallet and the billing for you.
Walkthrough
How it works
- 1
Sign in
Log in with email, Google, or Discord — no wallet extension or seed phrase needed.
- 2
Wallet auto-created
NovaPilot provisions a secure Circle Developer-Controlled Wallet for you automatically on first login.
- 3
Deposit USDC
Send USDC to your personal deposit address. Your balance updates automatically once the deposit confirms on-chain.
- 4
Pick a model
Choose from AI models across Anthropic, OpenAI, Google, and OpenRouter — switch anytime, mid-conversation or not.
- 5
Chat & use
Send prompts and get streamed responses, the same experience as using a provider's own app.
- 6
Automatic billing
Token usage is calculated per request and deducted from your USDC balance instantly — no manual tracking.
Features
What NovaPilot gives you
Unified USDC balance
One balance powers every supported AI model — no separate accounts or cards per provider.
Multi-provider AI router
Anthropic, OpenAI, Google, and OpenRouter models through one consistent interface.
Real-time streaming
Responses stream token-by-token, matching the latency you'd get from a provider directly.
Usage history & dashboard
Every model call, token count, and USDC cost — searchable, paginated, exportable.
Simple, secure login
Email, Google, or Discord via Privy. Your wallet is created and custodied for you.
Pay-as-you-go billing
Only pay for tokens you use. No subscriptions, no minimum spend, no idle fees.
Integration
For software engineers
If you're building a tool, bot, or internal app on top of NovaPilot, this is the part that matters. The same router your dashboard chat uses is available directly.
One API, every model
A single request shape covers Anthropic, OpenAI, Google, and OpenRouter. Switch providers by changing a model string — no separate SDKs, auth schemes, or billing integrations to maintain.
Streaming built on the Vercel AI SDK
Responses stream over standard SSE, compatible with the Vercel AI SDK's useChat and streamText helpers out of the box in your own frontend.
On-chain deposit webhooks
Circle webhook events sync your balance the moment a deposit confirms, with signature verification so you can trust every payload.
Predictable rate limits
Redis-backed limits protect your account from runaway loops during development, with clear per-endpoint thresholds you can plan around.
Usage-log API
Pull paginated, per-request logs — model used, input/output tokens, USDC cost, and timestamp — to reconcile spend in your own systems.
Scoped auth, no shared secrets
Requests are authenticated per-user; there's no API key to leak into a frontend bundle or shared repo.
fetch("https://api.novapilot.dev/v1/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include", // session-based auth, no API key in the client
body: JSON.stringify({
model: "claude-sonnet-5",
messages: [{ role: "user", content: "Summarize this transaction log" }],
stream: true,
}),
});Every response is streamed as it's generated. On completion, a usage entry is written with the exact input/output token counts and USDC cost for that call — visible immediately in the Usage History API.
Billing
Billing & usage tracking
Metering
Input and output tokens are counted per request and priced per model, matching each provider's published rates.
Settlement
Cost is deducted from your USDC balance the moment a response finishes — as a ledger entry, not an on-chain transfer per request.
Visibility
Every deduction appears instantly in Usage History with model, token counts, and cost — searchable and paginated.
API Marketplace
Publish or consume any HTTP API
NovaPilot Marketplace lets any developer wrap an existing API behind a NovaPilot proxy URL, price it per 1,000 calls, and get paid in USDC — while any developer can subscribe and pay per call from the same wallet used for AI access.
Creator publishes
Configure the upstream URL, HTTP method, path, auth type, and price. NovaPilot generates a public proxy endpoint.
Consumer subscribes
Deposit USDC once, browse the marketplace, subscribe to an API, and receive a scoped consumer key.
NovaPilot settles
Each call reserves, forwards, meters, and finalizes billing — 98% to the creator, 2% platform fee.
Publish any HTTP API
Wrap almost any existing REST endpoint — weather, SMS, data, finance — behind a NovaPilot proxy URL in a few steps.
Instant USDC settlement
No 30-day holds, no Payoneer, no 3% gateway fee. Earnings accrue per call and are withdrawable directly from your creator dashboard.
Your secret never leaves the vault
Upstream API keys and tokens are AES-256 encrypted at rest. NovaPilot injects them server-side on every forwarded call — consumers and even the dashboard UI never see the raw value.
Generic auth engine
Configure API key (header, query, or path), Bearer, Basic, or a custom header — no hand-written integration code per provider.
Auto-verified badge
Pass an email check and an upstream ping test, then earn a verified badge automatically after admin review — no manual ID checks.
SSRF-hardened proxy
Every upstream target is validated against private IP ranges and re-checked at request time, with DNS-rebinding protection built in.
For API creators
Publish an API in four steps
Every existing REST API — weather, SMS, currency, internal tools — can become a monetized listing without changing a line of its own code.
- 1
Basic details
Name, slug, category, and a description consumers will read on the listing page.
- 2
Endpoint configuration
Base URL of your upstream server, the HTTP method, and a path template (e.g. /v6/{apiKey}/latest/{base}) with placeholders for dynamic segments.
- 3
Authentication
Pick how your upstream API authenticates — none, API key (header, query, or path), bearer token, basic auth, or a custom header — and provide the secret once. It's encrypted before it's stored.
- 4
Pricing & publish
Set a price per 1,000 calls. The listing enters review; once approved it goes live at your generated proxy URL.
Earnings
98% of each call's price accrues to your available balance; NovaPilot keeps a 2% platform fee. Withdraw USDC to any wallet address directly from your Earnings dashboard — no lock-in, no scheduled payout window.
Verified badge
Verify your email and pass an upstream ping test to publish. A NovaPilot admin then reviews the listing once; approved creators receive a verified badge shown to every consumer browsing the marketplace.
POST /api/marketplace/creator/apis
Authorization: Bearer <session>
Content-Type: application/json
{
"apiName": "Exchange Rate API",
"apiSlug": "exchange-rate-api",
"description": "Live currency exchange rates.",
"category": "Finance",
"targetBaseUrl": "https://v6.exchangerate-api.com",
"requestSpec": {
"method": "GET",
"pathTemplate": "/v6/{apiKey}/latest/{base}"
},
"authSpec": {
"type": "api_key_path",
"name": "apiKey"
},
"credentialValue": "your-upstream-secret",
"pricingModel": "PER_1K_CALLS",
"costPer1kCalls": 0.2
}For API consumers
Browse, subscribe, and call — from one balance
The USDC balance you already use for AI chat is the same balance that pays for marketplace API calls. No separate top-up, no new payment method.
- 1
Browse the marketplace
Filter by category, search by name, and sort by popularity, price, or latency. Verified creators are flagged directly on the listing card.
- 2
Subscribe
Subscribing to a listing generates a scoped consumer key, shown once — copy it immediately, as it isn't stored in plaintext and can't be retrieved again later.
- 3
Call the proxy endpoint
Send requests to your generated /v1/{slug}/... URL with your consumer key as a bearer token. NovaPilot authenticates you, reserves the estimated cost, forwards the call upstream, and settles the final charge.
- 4
Track usage & spend
Every call appears in your usage history with cost, latency, and status — pause or revoke your key any time.
curl https://api.novapilot.dev/v1/exchange-rate-api/latest/USD \ -H "Authorization: Bearer nvpt_live_xxxxxxxxxxxxxxxx"
Insufficient balance
If your available balance can't cover the estimated cost, the request is rejected with 402 Payment Required before it's forwarded upstream — you're never charged for a call you can't afford.
Reporting an API
If an API misbehaves, report it from the listing page. Reports raise a risk score and go through review — there is no automatic refund, which protects creators from abusive disputes while still resolving genuine issues.
Reference
Supported authentication types
Configured once at publish time. NovaPilot decrypts your credential in-memory and injects it on every forwarded request — consumers, and even the creator dashboard UI, never see the raw value again.
No authentication
Your upstream API is publicly accessible — NovaPilot forwards requests as-is, with no credential injected.
API key — header
The key is injected as a custom header, e.g. X-API-Key: <secret>.
API key — query parameter
The key is appended to the request URL as a query string parameter, e.g. ?api_key=<secret>.
API key — path variable
The key fills a placeholder inside your path template, e.g. /v6/{apiKey}/latest/{base}.
Bearer token
Injected as Authorization: Bearer <token> on every forwarded request.
Basic auth
Username and password are combined and base64-encoded into the Authorization header automatically.
Custom header
Any header name and value pair you define, with an optional prefix — for providers with a non-standard auth header.
Planned for a future release: OAuth 2.0, OAuth 1.0, AWS Signature V4, Digest auth, and mTLS — the underlying request/auth configuration is designed to support these without breaking existing listings.
Reference
Proxy request lifecycle & error codes
Every marketplace call follows the same reserve → forward → meter → finalize sequence, whether the upstream API is public or fully authenticated.
- 1. Consumer key is validated (SHA-256 hash lookup).
- 2.Current price is snapshotted from the listing's active price version.
- 3. Estimated cost is atomically reserved against your available balance.
- 4. The target URL is re-validated against private IP ranges (SSRF protection) immediately before the call executes.
- 5. The request is built from your configured method, path template, and auth spec, then forwarded upstream.
- 6. On response, the reservation is finalized: the actual charge is deducted, 98% credited to the creator, and the usage record marked complete.
| Status | Meaning |
|---|---|
| 401 | Invalid, missing, or revoked consumer key. |
| 402 | Insufficient USDC balance to cover the estimated cost. |
| 404 | API slug doesn't exist, or isn't in an APPROVED state. |
| 503 | The listing is suspended, or its upstream is failing health checks. |
| 502 / 504 | Upstream returned an error or timed out; your reservation is refunded automatically. |
Trust
Security & custody
- Your wallet is a Circle Developer-Controlled Wallet — created and secured on your behalf, no seed phrase for you to lose or leak.
- Login is handled by Privy (email, Google, or Discord); NovaPilot never sees or stores your password.
- Deposit confirmations arrive through signature-verified Circle webhooks, so balance updates can't be spoofed.
- Marketplace credentials (API keys, tokens, passwords) are encrypted with AES-256 before storage and only decrypted in-memory to build an outbound request — never logged, never returned in a response.
- Every upstream target is validated against private/loopback IP ranges and cloud metadata endpoints, both at publish time and again immediately before each proxied request, to prevent server-side request forgery.
FAQ
Common questions
Do I need a crypto wallet to sign up?
No. Sign in with email, Google, or Discord — NovaPilot creates a Circle-managed wallet for you automatically on first login.
How is usage billed?
Every request's token usage is calculated and deducted from your USDC balance in real time. There is nothing to track or reconcile manually.
Is this on Mainnet?
NovaPilot currently runs on Arc Testnet, shown by the badge in the top bar. Moving to Mainnet requires no change to how you use the app.
Can I use this to build my own product on top?
Yes — the same request/response shape your dashboard chat uses is available as an API, so you can call it from your own backend or script.
What happens if my balance runs out mid-request?
A request that would exceed your balance is rejected before it reaches the model provider, so you're never billed for a call you can't afford.
Which models are supported?
Every model exposed by Anthropic, OpenAI, Google, and OpenRouter that NovaPilot has priced in its model catalog — visible directly in the model picker.
Can I sell my own API on the marketplace?
Yes. Any developer can become a creator, publish an existing HTTP API, set a price per 1,000 calls, and earn USDC directly — no separate merchant account needed.
Can I be both a creator and a consumer?
Yes. There's no restriction — publish your own API to earn, and subscribe to other creators' APIs to consume, all from the same account and balance.
What happens if a consumer reports my API?
Reports raise a risk score rather than triggering an automatic refund. NovaPilot reviews the evidence before taking action — your available balance is only frozen if the dispute is confirmed.
Does NovaPilot ever see my upstream API's secret key?
It's stored encrypted (AES-256) and only decrypted in-memory at request time to build the outbound call. It's never returned in any API response, including to you in the dashboard.
Deposit once. Use any model. Publish or call any API.