# Unison: free inference, powered by zkAPI

## Choose Standard or Private

**Standard** uses remote MCP or the account REST API. It needs no zkAPI vault, voucher claim or local passphrase. Unison processes prompts and stores account history. **Private** uses the local zkAPI gateway, blind vouchers and encrypted local history; content goes directly to OpenRouter. Providers see content in both modes.

Both modes share the same eligible allowance and global spending limits. Standard usage and private voucher claims cannot spend the same credits twice. Switching modes does not reset credits or automatically transfer history.

For Standard, use `https://unisonai.xyz/mcp` or the REST API in the Standard account API section below. Manage scoped account keys at `/app/developers` with Standard selected. Wallet sign-in alone grants no free credits; eligible identity or holder access is required.

For Private, follow the local zkAPI instructions below and select Private at `/app/developers` to create a voucher claim credential. New vaults start with a five-credit session cap, which you can increase explicitly.


Unison is privacy first. Its zkAPI workspace and local agent gateway authorize capped inference sessions without sending conversation content through Unison’s account API. Free inference uses your eligible daily allowance, claimed as blinded vouchers. Your agent sends prompts directly to OpenRouter; the provider and model processor see content.

The private workspace and free-inference vouchers are live at **https://unisonai.xyz**. Read `/api/zkapi/config` anonymously before using a deployment; `enabled` and `nativeReady` describe its current capabilities. Native-funded inference stays disabled until its separate escape operator is commissioned. Claiming without an explicit amount uses at most 50 credits, so larger holder allowances remain available for later claims.

## Setup

Use Node.js 24 or newer and the project distribution with its built crypto engine. Start with `/app/developers` to create a **voucher-claim key**. Store it in a private local file. It can claim blinded vouchers for the same eligible account within its daily and total limits; it cannot call the account inference API. An extra agent or key grants no extra allowance. Alternatively, export your encrypted browser vault and restore it into a fresh local gateway vault file.

Set `UNISON_ORIGIN` to the exact deployment origin, `UNISON_PRIVATE_VAULT` to your encrypted JSON file, and optionally `UNISON_ISSUANCE_KEY_FILE` to the scoped claim-key file. The CLI asks for a passphrase through a hidden terminal prompt. For a noninteractive MCP host, supply `UNISON_VAULT_PASSPHRASE` from a RAM-backed secret manager; the gateway removes it from its environment after reading it. Keep credentials and passphrases out of prompts, arguments, source control and logs.

```sh
export UNISON_ORIGIN=https://unisonai.xyz
export UNISON_PRIVATE_VAULT=/absolute/private/encrypted-vault.json
export UNISON_ISSUANCE_KEY_FILE=/absolute/private/voucher-claim.key
node scripts/privacy/gateway.mjs stdio
```

Configure your MCP client to launch that command with the same environment. This gateway runs locally; it does not forward inference through the public `/mcp` endpoint.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `unison_models` | Discover configured models without generating or signing |
| `unison_private_status` | Inspect local voucher denominations and original sessions |
| `unison_claim_free` | Blindly claim eligible free credits with the scoped issuer key |
| `unison_generate` | Generate directly with a capped temporary provider key |
| `unison_recover` | Recover the original session, usage and blinded change |
| `unison_recover_video` | Read and download the original video task |
| `unison_end_session` | Disable the original key before reconciliation |

Generate with an exact model ID, kind, prompt, a unique 16–100 character request ID, and your maximum session credits. Free vouchers are the default. Purchased vouchers require `usePurchasedCredits: true`; funded notes require an explicit note ID through the local HTTP interface. A voucher denomination may be smaller than your selected maximum; the client never silently consumes a larger voucher or falls back to purchased credits. Check available denominations before selecting a cap.

One session key can serve several text or media requests. It has a dollar cap and expiry: five minutes normally, thirty minutes for video. The service’s per-request, daily, lifetime and concurrency limits also apply. End the session before withdrawing a note; billing waits for key retirement, a 90-second quiescence window and stable provider usage samples. The provider’s management meter is not a signed receipt or a guarantee that its accounting can never change later.

## Local OpenAI-compatible interface

Set `UNISON_GATEWAY_TOKEN` to a local random bearer credential of at least 32 characters from your secret store. The listener binds only to `127.0.0.1`, validates Host and Origin, and accepts no unauthenticated requests.

```sh
node scripts/privacy/gateway.mjs http
# SDK base URL: http://127.0.0.1:4319/v1
```

Supported completed-response routes: `GET /v1/models`, `POST /v1/chat/completions`, `/v1/images/generations`, `/v1/audio/speech`, and `/v1/videos`. Supply a unique `Idempotency-Key` for each generation and reuse it only for that same original request. Streaming is not implemented. Audio returns audio bytes; images return base64 data. Videos return an original task identity for subsequent recovery and content retrieval. `GET /v1/private/status`, `POST /v1/private/claim`, `/recover`, and `/retire` manage local custody.

## Privacy and recovery

Eligibility is authenticated only when vouchers are claimed. RFC 9474 RSA blind signatures conceal the random redemption serial from the issuer. Native notes use Groth16 BN254 proofs of a registered funded balance. Inference redemption omits cookies, account headers and prompt content. Deposit and withdrawal transactions remain public, and timing, IP addresses and note-path reads may correlate activity.

Conversation history, vouchers, notes and pending-operation journals are encrypted locally using AES-GCM and a passphrase-derived key. Back up the encrypted vault after a claim or deposit. Losing the vault or passphrase can lose access to credits and notes. The gateway is part of your trusted local environment; unlocked data and provider keys are in RAM.

Keep original request, session, video-task and transaction IDs. An uncertain provider creation is never sent again automatically. Reconcile the original key or task. If a wallet response is lost, recover its original transaction hash rather than creating a replacement transaction. Independent escape withdrawal uses the selected wallet’s RPC when the Unison backend is unavailable and waits one day for challenges.

The adapted circuit uses experimental setup parameters and has not been independently audited. Unison retains one EOA administrator with immediate upgrade, configuration, pause and recovery control. This is private access authorization, not a claim of complete anonymity, trustless provider metering, or affiliation with the Ethereum Foundation.

## Existing integrations

The remote `/mcp` and `/api/v1` account integrations remain available for compatibility and account-history recovery. They retain their existing account-linked behavior. Read [the legacy guide](/agents-legacy.md) when maintaining an existing integration. The local zkAPI gateway is the private path.

Retiring a key does not make provider metering final. The remaining original cap stays reserved against the service budget, including after a local refund or blinded change. Delayed charges are recorded as service expense; already issued private note successors and vouchers are not rewritten. This conservative reserve has no assumed automatic release deadline.

Wallet authentication alone grants zero free credits. A linked eligible social identity or qualifying holder balance supplies the shared daily allowance; purchased credits retain their existing obligations. Claiming vouchers does not create an additional allowance.


# Unison token and holder access

This page is generated from the running service. Read /token.json for machine-readable addresses and status.

Network: Robinhood Chain (chain ID 4663).

Status: active.

Token: 0x79Be8ec1A4F4f9EFeC49cEe5AD5E1D4B965fC05D

Treasury: 0x2e1c13694Fc60d10F2B8D22D500360615BBc4996

Pons factory: 0x7eD598BcEf8bd9Edd8C97A195C6d13f40801EC7e

Treasury admin: 0x3f07C29CA6552d64882b34091C410336E1aC7599

[Token explorer](https://robinhoodchain.blockscout.com/address/0x79Be8ec1A4F4f9EFeC49cEe5AD5E1D4B965fC05D) · [Treasury explorer](https://robinhoodchain.blockscout.com/address/0x2e1c13694Fc60d10F2B8D22D500360615BBc4996)

Base daily allowances: authenticated entry below 100,000 tokens: 50; 100,000–under 1,000,000: 200; 1,000,000–under 10,000,000: 500; 10,000,000+: 1,000 credits. Wallet-only agents need at least 100,000 eligible tokens or purchased credits.

Treasury boost thresholds: $0 → 1.00×; $1,000 → 1.10×; $2,500 → 1.20×; $5,000 → 1.30×; $10,000 → 1.40×; $50,000 → 1.50×; $100,000 → 2.00×. Each step activates at its threshold and stays in effect until the next. Below $1,000 there is no boost; above $100,000 it stays capped at 2×. Credits round down to whole credits. Only the observed native balance in the configured treasury counts, valued at a cached ETH/USD bid. Unclaimed rewards, unsold tokens and projected fees do not count. A missing/stale valuation uses 1× and is reported as unavailable. This changes service allowances; the treasury contract's legacy requiredTokens getter is not the access rule for this policy. Current multiplier: 1×.

Keep eligible tokens in your wallet; no staking or approval is required. Unused holdings qualify immediately. Spending holder credits allocates the supporting tokens to that account until 00:00 UTC. Allocated tokens move first on transfers and cannot support another account that day, including after a trade. Selling reduces access; returning tokens does not reset usage. Social and holder allowances use the greater limit, not their sum. Workspace, REST and MCP share one ledger.

Creator fee recipient: 0x2e1c13694Fc60d10F2B8D22D500360615BBc4996. Matches this treasury: true.

AI usage depends on available provider credits and configured spending limits. Temporary card top-ups fund OpenRouter; crypto-treasury-to-provider top-ups are not automated.