Managed invocation & credits

Status: live, early access. Accounts are operator-onboarded; there is no self-serve signup yet. Contact us to get an account and your owner scope token.

Discovery tells your agent which service to call. Managed invocation goes one step further: Nitrograph runs the call. Your agent authorizes a quoted price; Nitrograph pays the provider from its own treasury, validates the response against a versioned ruleset, and charges your prepaid credits only when the work passed. Failed work is refunded in full.

Unlike direct calls — which never touch Nitrograph — a managed invocation is explicitly in the request path: Nitrograph executes the provider call and processes its response in order to pay, validate, and settle it.

The loop

quote → hold → pay upstream → validate → settle
                                       ↘ refund

Quote. POST /v1/invoke prices the call: the upstream provider price plus Nitrograph's platform take (currently 20%, included in the quote — what you authorize is exactly what a validated pass charges). max_price_micro_usd caps what you are willing to authorize.
Hold. The quoted amount is held against your credits balance. No hold, no upstream call.
Pay upstream. Nitrograph's treasury answers the provider's x402 payment challenge. Your agent holds no wallet and no provider keys.
Validate. A versioned ruleset checks the work — transport checks always (status, shape, non-empty), semantic checks per service type (enrichment results must contain real fields; search results must be well-formed and distinct; scrapes must clear bot-wall detection). The ruleset version is stamped into the result and the receipt.
Settle or refund. A validated pass settles the hold and writes a signed receipt. Anything else releases the hold in full — Nitrograph absorbs the upstream spend, not you.

Retries are idempotent: an identical request in the same minute returns the original invocation — no second hold, no second upstream call. GET /v1/invocations/:id returns the invocation state and receipt references.

You can invoke by slug, or pass an intent string and let Nitrograph route to the best certified supplier whose quote fits your price cap.

Credits

Managed invocations are funded by a prepaid credits account with an append-only ledger. All amounts are integer micro-USD (1,000,000 = $1.00).

Endpoint	Purpose
`POST /v1/credits/checkout`	Stripe top-up. `{ "amount_usd": 50 }` → `{ url }`. Allowed amounts: $20, $50, $100, $250, $500
`GET /v1/credits/balance`	`{ balance_micro_usd, open_holds_micro_usd, account_status }`
`GET /v1/credits/statement?from&to`	Ledger rows; `&format=csv` for export
`GET /v1/credits/receipts/:id`	A signed receipt — visible only to the paying account

Statement rows carry a kind from a fixed vocabulary: topup (+), hold (−), release (+), settle (−), refund (+), adjustment (±), chargeback (−). A settled call appears as a release + settle pair.

Credits are prepaid for platform services, non-transferable, refundable only as unused balance on request, and subject to a stated expiry.

Receipts

Every settlement and refund writes a signed receipt: a content-addressed, Ed25519-signed JWS object (nitrograph.receipt.v1) recording payer, payee, subject, outcome, amount, and the validation ruleset version. Receipts are the marketplace's evidence layer — fetchable by the paying account, verifiable offline, and designed to batch-anchor to the Nitrograph network's consensus topics once that protocol layer certifies.

Auth: agent-scope tokens

Commerce endpoints authenticate with a Bearer agent-scope token: a constrained spending credential issued against your account.

The owner scope is minted when the operator creates your account.
POST /v1/agent-scopes mints additional non-owner spending scopes with their own caps — give each agent its own scope.
GET /v1/agent-scopes lists scopes and caps; DELETE /v1/agent-scopes/:id revokes immediately.

Treat scope tokens like money. Keep them out of code, logs, and anything that leaves your runtime; send them only to api.nitrograph.com.

What Nitrograph sees, and keeps

On a managed invocation, Nitrograph processes the request you send and the provider's response — that is what paying, validating, and refunding require. Settlement evidence (receipts, validation results, ledger entries) is retained; it is what makes your refunds and statements provable. Direct calls made outside /v1/invoke never touch Nitrograph.

Failure semantics worth knowing

Unpaid 402s and caller-shaped 4xx are neutral: refunded without dinging the provider's reputation.
Provider failures feed ranking: settles and refunds update the trust signals that order future discovery results.
Suppliers who fail too often become unroutable: a sustained refund spike auto-pauses a supplier out of routing pending manual review. Paused suppliers can't take new money.