> ## Documentation Index > Fetch the complete documentation index at: https://gora.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```json theme={null} { "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=` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.