Structured AI calls and testnet credits

Schema-validated output, flat call fees, reservations and separate funding balances.

Structured AI calls and testnet credits

WASM imports gora.llm_json(ptr, len, out_ptr, out_cap) -> i32. Send a prompt, instructions and object-root JSON schema. The host returns validated JSON or a negative error; never trade/write a transaction after parsing or schema failure.

{
  "instructions": "Score the observation and explain uncertainty.",
  "prompt": "Five users asked for report exports.",
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["score", "reason"],
    "properties": {
      "score": {"type": "integer", "minimum": 0, "maximum": 100},
      "reason": {"type": "string", "maxLength": 500}
    }
  },
  "max_completion_tokens": 300
}

The managed node uses its configured Azure GPT-5.5 deployment. Model, endpoint and key are operator-side; apps cannot override them or read credentials. Validators replay the captured response, not another paid call per vote.

Required testnet GORA payment

The launch policy requires prepaid testnet GORA before the first AI call. There is no free AI starter balance. Existing execution credits, validator stake, keeper allowances and native gas balances do not buy AI calls.

The initial published price is 1 test GORA per dispatched provider attempt, the same on all three supported testnets. This is configurable operator policy, not a mainnet charge. Always read the published /billing/ai/config and the exact invoice before signing. The price and chain atomic amount are fixed in each invoice. A dispatch that receives a provider error still costs one call credit; input rejected before dispatch and replay of a captured result cost no additional AI credit. No automatic main-wallet spending is authorized by an app session.

Payment routes and mandatory paid-call enforcement were activated on September 21. Live unpaid calls return 402. Independent Base and Solana paid AI, confirmed chain writes, revocation and recovery have passed. Native-wallet acceptance is still in progress; activation is not proof that all launch gates have passed.

Buy calls for an agent

1. Authenticate using an app-scoped wallet session or a private developer token.
2. POST /instances/{id}/ai-credits/quotes with {"chain":"base","payer":"0x…","call_credits":5}. Use solana or algorand with the corresponding testnet wallet. A wallet session must pay from that same chain’s authenticated owner wallet.
3. Review the returned quote: network, canonical GORA token, treasury, amount, agent, price version and expiry. Sign its payment transaction using your wallet. Retain quote_id and transaction ID before leaving the page.
4. POST /instances/{id}/ai-credits/payments with {"quote_id":"…","transaction_id":"…"}. The server verifies the actual token transfer and invoice commitment, not a browser success flag.
5. Read /instances/{id}/ai-credits. Its paid_ai.available balance must be positive before an LLM dispatch can proceed. Invoke the agent with a stable request ID and inspect execution and settlement independently.

For an app-scoped payer rather than an individual agent, replace /instances/{id} with /apps/{app_id}. Credits are scoped to the authenticated owner and app or instance; they are not shared with another user’s agents.

Base uses the canonical test GORA ERC-20 transfer plus an invoice commitment in calldata. It waits for a finalized L2 block, which can take about 20 minutes. Solana uses SPL TransferChecked and an invoice Memo at finalized commitment. Algorand uses an ASA transfer with an invoice note and confirmed round. Pay within the invoice’s 30-minute inclusion window. Finality may arrive after that window; retry confirmation of the original payment rather than sending another one.

The native SDK helper is Gora.aiCredits("quote", instanceId, {chain, payer, call_credits}); config, balance and confirm are also supported in the candidate mobile build. Purchasing still requires a separately reviewed wallet transaction through the app’s declared action. The session and AI-credit helper cannot sign or spend.

Recover the original invoice

The recovery API and updated Signal Lab, Northstar and Harbor UIs are deployed on the public testnet. Updated clients must fail closed if the endpoint is unavailable. Native original-payment confirmation is a separate acceptance check.

Use authenticated GET /apps/{app_id}/ai-credits/quotes to discover all of this owner’s app and instance invoices. Use GET /instances/{id}/ai-credits/quotes for a single instance. Both support the /v1 prefix and return recovery_only: true, invoices and next_before. Each item contains the original quote, transaction_id (possibly null), and status issued, verified or credited. Follow ?before=<next_before> until next_before is null; pages contain at most 50 invoices, including expired ones. The candidate mobile helper is Gora.aiCredits("invoices", null, {before}) for app-wide history, or replace null with an instance ID.

Issued plus a null transaction ID does not mean unpaid. The wallet may have broadcast a transfer whose acknowledgement was lost. Restore missing records as confirmation-only, retain any existing or corrupt journal for review, and persist the original transaction ID before retrying the payment-confirmation endpoint. Check the full owner/app history before creating another invoice after storage loss; selecting another agent must not bypass an unknown payment. Never re-sign a recovered invoice, silently replace it after expiry, or clear an uncertain record. The confirmation response must match the original owner, app, instance, quote, transaction, token, amount, price version and credit count.

Listing makes no chain request or credit change. Confirmation verifies the original transfer and is idempotent; it never signs or broadcasts. An invoice with no recoverable transaction evidence needs support review, not another payment. Persist public journals separately from wallet secrets and session tokens. Native app storage is isolated by app and bridge origin; uninstalling or clearing browser data still requires server-assisted recovery.

GET /v1/billing/policy describes runtime metering. /credits responses retain ordinary execution total, reserved, available and add separate paid_ai balances. One paid call is reserved durably immediately before provider I/O; the captured result is reused on retry. An uncertain provider attempt is held for operator review, never silently retried as another free or duplicate call. Reuse request IDs after HTTP uncertainty.

Separate balances

Balance	Pays for
Ordinary nonredeemable execution credits	Gora execution only
Prepaid AI call credits bought with test GORA	Dispatched AI provider attempts
Test ETH / devnet SOL / test ALGO	Chain fees and rent/minimums
Test GORA stake	Validator participation
App assets/collateral	App transfers, trades or positions

Adding ALGO does not refill execution credits. GORA stake does not pay an agent’s AI bill. Creating a signer does not fund it. Credits are not redeemable tokens.

Infrastructure keepers can receive an explicitly capped, audited daily allowance bound to reviewed app/instance/payer/artifact and the current authorized schedule. It is separate from user balances, not an unlimited public auto-refill. Monitor both execution reservations and chain fee reserves.

Apps must handle exhausted credits, provider errors, timeouts and pending chain results. Quota is not measured throughput; no hundreds-of-agents load test is claimed. Obtain user consent before sharing data with third-party AI. Never send wallet seeds, developer tokens, API keys or confidential instructions.