# Voltio for agents

Voltio sells discounted AI inference as an on-chain credit token. An agent with a wallet can buy credit, activate it
into an API balance, derive an API key by signing a message, and call models through an OpenAI-compatible gateway.
No account or human approval is needed at any step.

- Chain: Robinhood Chain. Mainnet chain id `4663`, testnet chain id `46630`.
- Payment token: USDG (6 decimals).
- Credit token: JOULE (ERC-20, 6 decimals). 1 JOULE = $1 of usage at provider list prices.
- Gateway base URL: `https://voltiodotso.app/api/v1` (OpenAI Chat Completions dialect, provider-prefixed model ids).
- Live contract addresses: see `https://voltiodotso.app/protocol`.

## Lifecycle

1. **Stake**: VOLT holders stake in `VoltStaking` (tiers: 0 flexible 1.00x, 1 30d 1.25x, 2 90d 1.5x, 3 180d 2x).
2. **Earn**: every finalized hour, JOULE is minted to stakers pro rata to weight.
3. **Trade**: JOULE is listed on the Grid (`VoltExchange`) at 0 to 90% off in 1% steps, or traded on a DEX.
4. **Activate**: `Joule.activate(amount, beneficiary)` burns JOULE into a non-transferable API balance for `beneficiary`.
5. **Call**: the gateway meters each request against that balance at list price.

## Buying

Buys fill from the deepest discount first; within a level, first-in first-out. At most 64 orders per buy.

```solidity
// Quote: how much USDG for `creditOut` JOULE (6 dp)?
Quote q = exchange.getQuoteForCredit(creditOut, 64);
// q = (creditOut, usdgSpent, feeAtoms, fills, reason)
uint256 budget = q.usdgSpent + q.feeAtoms;   // protocol fee is on top of the seller price
usdg.approve(address(exchange), budget);
exchange.buy(budget, minCreditOut, recipient, 64);
```

- `buyWithReferral(usdgIn, minCreditOut, recipient, maxFills, referrer)`: same as `buy`; binds `referrer` to the buyer on the first fee-paying buy. The referrer earns a share of the protocol fee.
- `buyAndActivate(usdgIn, minCreditOut, bytes32 beneficiary, maxFills)`: buys and activates in one call. No protocol fee; the JOULE activation fee applies. Quote with `getActivationQuote(usdgIn, maxFills)` which returns `(quote, creditedAtoms, activationFeeAtoms)`.
- `beneficiary` is the address left-padded to 32 bytes: `bytes32(uint256(uint160(addr)))`, or in viem `pad(addr, { size: 32 })`.
- Quote `reason`: 0 filled in full, 1 liquidity exhausted, 2 budget too small for next unit, 3 hit fill limit.
- Take `minCreditOut` from an off-chain quote minus your slippage tolerance (e.g. 0.5%).

## Selling

- `sell(amount, uint16 discountBps, uint64 expiry)`: discount is a multiple of 100 up to 9000; expiry 0 = never. Approve JOULE first.
- `cancel(orderId)`, `reprice(orderId, newDiscountBps, newExpiry)`.
- `orderIdsOf(seller)`, `orders(id)` → `(seller, level, expiry, prev, next, remaining, initial)`.
- Proceeds accrue in USDG: `proceedsOf(seller)`, claim with `claimProceeds()` or `claimProceedsAsVolt(minVoltOut)`.
- Expired orders refund JOULE to `expiredRefundOf(seller)`, claim with `claimExpiredRefund()`.
- `getBook()` → `(uint256[91] liquidity, uint256[91] counts)`, index = discount percent.

## API key

The key is derived from a wallet signature; nothing is registered server-side.

```ts
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const chainId = 46630; // 4663 on mainnet
const epoch = 1;       // bump to rotate; first use of a higher epoch revokes all older keys
const message = `Voltio API key · chain ${chainId} · epoch ${epoch}`;
const signature = await account.signMessage({ message });
const apiKey = `sk-volt-${epoch}-${Buffer.from(signature.slice(2), "hex").toString("base64")}`;
```

The message must match byte for byte, including the `·` (U+00B7) separators.

## Gateway

```sh
# Chat completion
curl https://voltiodotso.app/api/v1/chat/completions \
  -H "Authorization: Bearer $VOLTIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-5","messages":[{"role":"user","content":"hello"}]}'

# Balance
curl https://voltiodotso.app/api/v1/key -H "Authorization: Bearer $VOLTIO_KEY"
# → {"object":"key","address":"0x…","balance":{"currency":"USD","available":…,"used":…,"credited":…},
#    "rate_limit":{"requests_per_minute":…,"concurrent":…}}

# Models (public): OpenRouter-shaped, prices in USD per token
curl https://voltiodotso.app/api/v1/models

# Usage for the key
curl "https://voltiodotso.app/api/v1/usage?days=14" -H "Authorization: Bearer $VOLTIO_KEY"
```

## Notes

- JOULE is a prepaid grant of product access, not an investment or redeemable for cash. Activated balance is not withdrawable.
- Nothing here is financial advice.