What this router has enabled. A router at launch serves the core launch surface: chat, completions, embeddings, the model catalogue, API keys, prepaid credits, per-call payments, signed receipts and attestation records. Every other section stays here for reference and is marked “Built, not enabled at launch”: the feature is written, a router on the core surface answers its routes with 404 not_enabled, and it is switched on only after its own review.
Quickstart
Trellis speaks the OpenAI-compatible chat API. Point an existing client at /api/v1 and use a Trellis key.
// Change two lines: the base URL and the key.
const client = new OpenAI({
baseURL: process.env.TRELLIS_BASE_URL, // "<your router>/api/v1"
apiKey: process.env.TRELLIS_API_KEY, // "sk-tr-v1-…"
});
const generation = await client.chat.completions.create({
model: "meta-llama/llama-3.3-70b-instruct",
messages: [{ role: "user", content: "Hello, Trellis." }],
});Sign in from your account to see your progress here.
Set TRELLIS_API_KEY to your key in your shell before running this command. Choose a model from the model list.
curl "https://trellis.example/api/v1/chat/completions" \
-H "Authorization: Bearer $TRELLIS_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"meta-llama/llama-3.3-70b-instruct","messages":[{"role":"user","content":"Hello"}],"max_tokens":32}'For ordinary calls, the router reads request text in memory to route it. See what we keep.
Payments
Every way to pay settles in USDC on Solana mainnet-beta (CAIP-2 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v). Current pricing: zero markup on every method. You pay the price of the inference you use, per token, at the rate of the host that serves it; hosts receive their full price. Two things are not part of that price and are not a markup: a per-call (x402) payment has a minimum size (0.03 USDC by default), and when the router pays the Solana network fee of your per-call payment it passes that fee on at cost, as its own line (network_fee on the receipt, quoted beforehand as network_fee_max_usdc). Per call has the details.
Before a call is sent to a provider the router holds an amount on your balance. The hold is a worst-case bound, not an estimate: the request counted from its bytes for every input shape, plus the output cap, which is always sent to the provider. It is several times a typical charge. You are charged what the call used and never more than the hold; if a provider reports more than was held, you pay the hold, and the response and the receipt carry cost_details.over_hold. A request whose input cannot be bounded (for example an image for a model whose catalogue entry declares no per-image limit) is refused with 400 unboundable_input and nothing is charged.
At launch a router takes three of the methods below: prepaid credits, per-call (x402) payments and tabs (an open tab named in the X-Trellis-Tab header with a session-key voucher). Blind tokens, paying with a tokenized stock and bringing your own key are written and carry a “Built, not enabled at launch” line.
Calls that end early
A provider that is working on a call bills it whether or not anyone is still listening, so a call that does not end normally is charged what the provider can bill, and never more than the hold. This is current behaviour and can change.
| What happened | What you are charged |
|---|---|
| The provider answered and reported usage | The reported usage. An empty answer the provider metered is delivered and charged too. |
| The provider answered and reported no usage | A conservative bound: the prompt at its bound (the figure the hold was computed from) plus the bytes received. The receipt marks the tokens estimated. |
| The provider failed without producing tokens: a 5xx, a refused or reset connection, a stream that broke before any content, an empty answer with no usage | Nothing. The next provider is tried; if all fail the answer is 502 providers_unavailable. |
| The router’s own time limit ran out while a provider had the request | The prompt bound at that provider’s input price. No other provider is tried, and the answer is 504 provider_timeout with a signed receipt. |
| You hung up on a stream | What was generated: the provider’s reported usage when it arrives within 15 seconds, otherwise the bound over every token the provider sent. |
| You left a call that was not streamed | The call runs to its end and is charged its reported usage. |
| An attested-lane answer whose gateway receipt does not show a verified upstream | The answer is withheld (502 upstream_not_attested). The gateway had already done the work, so the call is charged as usual, and the signed receipt records the verification result. |
Once a day the router compares what each provider is owed with what its calls collected from callers, and with the provider’s invoice where the operator recorded one; a gap raises an alarm for the operator and moves no money. Make-good refunds, the rules that return money after the fact, are off by default.
Prepaid credits
A key's credits live in a trellis_credits account seeded by the key hash (the SHA-256 of the key's public key, shown under Payments). POST /api/v1/credits/deposit-tx with an amount and your wallet address returns one unsigned deposit transaction; your wallet signs it as fee payer and sends it, and the balance is credited once the transaction is finalized, usually seconds. When the key has no owner wallet yet, the same transaction registers your wallet as the key’s owner (the answer names it under owner.registers): the owner can ask for a closure without the key and take any closure of the key back. Send register_owner: false to fund someone else’s key without becoming its owner. A plain USDC transfer to the program or its vault is not a deposit and is not credited; where a router reports solana_pay_transfer in GET /api/v1/credits, the dashboard also shows a Solana Pay code for a wallet app. Deposits are refused above the per-key cap (cap_usdc in GET /api/v1/credits).
curl -s https://trellis.example/api/v1/credits/deposit-tx \
-H "Authorization: Bearer $TRELLIS_API_KEY" -H "content-type: application/json" \
-d '{"amount":"25","payer":"<your wallet address>"}'
# data.transaction: an unsigned Solana transaction (base64) for your wallet to sign and send.
# data.key_hash, data.accounts.vault, data.expires_at_block_height: what the transaction commits to.
# data.refund_to: the USDC account this deposit is paid from. If the key is ever closed, what is left of it goes back there.Credits are spend-only. There is no withdrawal: USDC leaves the vault only as settlement to hosts, as account-closure refunds, and as the sweep of an expired balance to the treasury. Any wallet can top up a key; paying in gives that wallet no control over the key. The smallest deposit is 1 USDC. Under current policy a balance expires 12 months after the last deposit, with a 30-day notice before what is unspent moves to the treasury; expiry is built, not enabled at launch, so a router at launch sends no notice and sweeps nothing. POST /api/v1/credits/close closes the key and returns what is left to the wallets that paid it in; it is paid by the settlement service after a 72-hour delay and a sanctions check of the accounts being paid, not on demand.
Closing an account
Closing gives the money back to the wallets that paid it in. Each wallet that deposited to the key gets its share of what is left, never more than it put in, in the USDC account it paid from. You do not choose where the refund goes, and neither can anyone else who holds the API key: a key can ask for a closure and take it back, and that is all. A leaked key therefore cannot be used to send your balance to someone else.
Call POST /api/v1/credits/close with the key as the bearer and {payer}, the wallet that will pay the fee. There is no destination field: a request that carries refund_to is refused with 400 refund_destination_fixed. The answer lists who will be paid back in refunds (one row per wallet that paid in: depositor, refund_to, deposited_units, refunded_units), so you can read it before anything is sent.
A closure is authorised by the key itself, and by nothing else: the on-chain close_account instruction must be signed by the key's own ed25519 keypair (the one whose public key hashes to the key hash), so no wallet can close a key, whoever deposited to it. The router signs the transaction as the key from that request (it stores neither the key nor its keypair) and returns it in transaction with signed_by_key: true. payer is any wallet: it adds its signature as fee payer, pays the network fee and a small rent, and sends the transaction before expires_at_block_height. Paying the fee does not make it the destination. Nothing else in the transaction may change, or the key's signature no longer covers it. transaction is null when the closure is already registered on chain. The dashboard does this under Payments with the connected wallet, and shows where the refund goes before the wallet opens; the SDKs have a helper.
curl -s https://trellis.example/api/v1/credits/close \
-H "Authorization: Bearer $TRELLIS_API_KEY" -H "content-type: application/json" \
-d '{"payer":"<the wallet that will pay the fee>"}'
# 201 {"data":{"id":"close_…","status":"queued","payable_at":"…","payer":"…","signed_by_key":true,
# "transaction":"<base64, already signed by the key>","expires_at_block_height":…,
# "refunds":[{"depositor":"<a wallet that paid in>","refund_to":"<the USDC account it paid from>",
# "deposited_units":"25000000","refunded_units":"0"}]}}
# The payer wallet adds its signature as fee payer and sends data.transaction before the blockhash expires.
# There is no destination to send: a request that carries refund_to is answered 400 refund_destination_fixed.import { Trellis, keypairSigner, sendTransaction } from "@trellis/sdk";
const client = new Trellis({ apiKey: process.env.TRELLIS_API_KEY }); // the key being closed
const payer = keypairSigner(walletSecretKey); // any wallet: it only pays the fee
const { closure, signed } = await client.credits.closeWith(payer); // the key's signature is already in place
console.log(closure.refunds); // who is paid back, and to which account
if (signed) await sendTransaction(signed, { rpcUrl }); // null: already registered on chainFrom the moment the closure is on chain the key is frozen: any call that would spend answers 409 with error.type: "credits_closing" and the closure's id in error.metadata.closure, until the refund is paid or the closure is taken back. It is not a transient error, so the SDKs do not retry it; use another key. The refund is what the key had not spent when it is paid, never more than the key's own deposits cover, and it waits for calls still in progress. Refunds are paid within an allowance that refills continuously and is kept apart from the one for host payouts, so a large refund, or many closures at once, can arrive in parts over days (refund_rate_limited). Over any 24 hours the allowance is a share (20% today) of the lowest balance the vault has had in the last 24 hours, never more than an absolute cap (25,000 USDC by default) and never less than 1,000 USDC, with a quarter of it available at once. A pause of deposits or settlements does not stop a closure, its cancellation or its refund.
Taking a closure back
Until the refund starts being paid you can change your mind. POST /api/v1/credits/close/cancel with {payer} returns a cancel_close transaction already signed by the key; the payer wallet signs and sends it as for the closure, and once it lands the key is open again with its balance. With no closure on chain the answer is 400 nothing_to_cancel; once a payment has been sent it is 409 refund_in_progress. Who can take a closure back: whoever asked for it, or the key’s registered owner wallet. The key itself can do it once in 60 days (after that 409 cancel_cooldown), so two holders of one key cannot keep cancelling each other; a wallet that merely deposited to the key has no say. Register an owner wallet with POST /api/v1/credits/owner-tx (signed by the key and by the wallet) when you create the key: the owner can close with as_owner, and a closure asked for that way cannot be cancelled with the API key.
curl -s https://trellis.example/api/v1/credits/close/cancel \
-H "Authorization: Bearer $TRELLIS_API_KEY" -H "content-type: application/json" \
-d '{"payer":"<the wallet that will pay the fee>"}'
# 200 {"data":{"transaction":"<base64, already signed by the key>","payer":"…","signed_by_key":true,"expires_at_block_height":…}}
# 400 nothing_to_cancel: no closure of this key is on chain. 409 refund_in_progress: a payment has already been sent.Disabling a key puts its closure on hold
If a key is disabled or revoked (DELETE /api/v1/keys/{hash}), a closure it started is not paid. This is what you want when a key has leaked: revoking it also stops the closure someone may have asked for with it. The answer to the revocation says so in data.closure_held, and the closure is listed with reason: "key_disabled". When the closure was your own and you want it to go ahead, an owner or admin of the account releases it with POST /api/v1/credits/close/release and the hash of the key. The refund still goes only to the wallets that paid in.
curl -s https://trellis.example/api/v1/credits/close/release \
-H "Authorization: Bearer $OWNER_OR_ADMIN_KEY" -H "content-type: application/json" \
-d '{"key":"<hash of the disabled key, as GET /api/v1/keys lists it>"}'
# 200 {"data":[{"id":"close_…","status":"registered","released":true,"payable_at":"…"}]}Sending your share to another wallet
A wallet that paid in can name another wallet to receive its own share, for example because the first one is being retired. Only that wallet can do it, with its own signature: POST /api/v1/credits/refund-destination-tx with {depositor, refund_to} returns an unsigned set_refund_destination transaction for the depositor's wallet to sign and send. The API key is not part of that transaction and cannot make this change. It moves no money; it only says where that wallet's share of a later refund is sent. A wallet that never deposited to the key gets 404.
curl -s https://trellis.example/api/v1/credits/refund-destination-tx \
-H "Authorization: Bearer $TRELLIS_API_KEY" -H "content-type: application/json" \
-d '{"depositor":"<the wallet that paid in>","refund_to":"<the wallet that should receive its share>"}'
# 200 {"data":{"transaction":"<base64, unsigned>","depositor":"…","refund_to":"…","current_refund_to":"…","expires_at_block_height":…}}
# Only the depositor's wallet can sign it. 404: that wallet never deposited to this key.GET /api/v1/credits/close lists the key's closures and their state: queued (prepared, not on chain yet), registered (on chain, waiting), paid, refused, failed or cancelled. Each row has refunds (one payment per wallet that paid in, with its account, the wallet that owns that account, the amount and whether it has been sent), refund_to (the wallets paid so far) and, while it waits, a reason: key_disabled (on hold), refund_rate_limited (paid in parts), refund_destination_unavailable (a wallet's account cannot receive right now), refund_work_capped (many wallets, paid a few per run, largest share first) or depositors_unknown. A refund is split over the wallets that paid in largest remaining share first. A payment line marked reversed was prepared and then not sent because the closure was taken back on chain; its amount is back on the balance.
Per call (x402)
A request without credits can carry an x402 payment: the exact scheme pays the call's price from your wallet, the tab scheme pays from an open tab. Both are verified and settled by the facilitator.
The quote in the 402 (accepts[0].maxAmountRequired, also price_usdc) is what the payment must carry. With the exact scheme the router pays the Solana network fee of your payment and passes it on at cost: the quote adds the most that fee can be (network_fee_max_usdc, 0.005 USDC at the default settings), and what is kept is the fee of your transaction as you signed it, converted at the router’s stated SOL price, with no margin on top. The receipt shows it as its own line (network_fee: lamports, USDC, the SOL price used). No quote is below the minimum payment (0.03 USDC by default); everything but the fee is credited to your wallet, and what the call does not use stays there as change for later calls (spend-only). Sponsored payments are limited per wallet, per source address and in total; past a limit the answer is 429 rate_limited, and you can always send the USDC transfer yourself and present its signature with X-Wallet-Auth. A wallet whose sponsored payment failed after it was sent is not sponsored again for 30 days (403 payer_not_sponsored). The network fee is cost recovery, not a markup: GET /api/v1/status reports, under per_call.x402.network_fees, the lamports the router paid beside the USDC it recovered over the last 30 days.
An exact payment is one transaction you build and sign with the router's fee payer (extra.feePayer in the 402) as its fee payer: one USDC TransferChecked to the payTo token account, sent base64 in X-PAYMENT. The fee payer co-signs only inside fixed bounds, and refuses anything else before it signs: exactly two signatures (the fee payer's and yours); the fee payer named in no instruction; at most one SetComputeUnitLimit (200,000 units or fewer) and one SetComputeUnitPrice (5,000,000 micro-lamports or fewer) with a priority fee of at most 10,000 lamports; and, when payTo's token account does not exist yet, at most one idempotent creation of it paid for by you, never by the fee payer. The SDKs build payments inside these bounds and refuse options that would leave them.
A transaction signature alone is not a payment claim. If you paid the transfer yourself and present its signature in X-PAYMENT instead of a signed payload, the request must also carry X-Wallet-Auth (below) from the wallet that paid; a landed transaction is public, so without it the answer is 401 payment_not_bound_to_caller and nothing is credited. The same header spends the change an earlier payment left on the wallet's account.
Wallet sign-in
A wallet gets an API key of its own account by signing one message. POST /api/v1/auth/wallet/challenge returns a one-time nonce and the exact message to sign: a Sign-In-With-Solana text that names the router's domain and URI, the wallet's address, the network, the nonce and a five-minute validity. The wallet signs those UTF-8 bytes as returned, and POST /api/v1/auth/wallet exchanges the signature for the key. The router verifies the signature over the message it issued and over nothing else; a client-built text, including the earlier trellis:wallet:v1 form that named no site, does not sign in. Before signing, check that domain is the router you are talking to and that the message names your own address: a challenge relayed from another site names that site. The dashboard and the SDKs make that check and refuse otherwise.
POST /api/v1/auth/wallet/challenge {"address":"<base58 wallet address>"}
# data: { nonce, message, domain, uri, chain_id, issued_at, expires_at, version: "trellis:wallet:v2" }
# message, to sign exactly as returned (UTF-8 bytes, ed25519, base58 signature):
# trellis.example wants you to sign in with your Solana account:
# <address>
#
# Sign in to Trellis with this wallet. Signing proves you hold the address: it sends no transaction and costs nothing.
#
# URI: https://trellis.example
# Version: 1
# Chain ID: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
# Nonce: <nonce>
# Issued At: <time>
# Expiration Time: <time, five minutes later>
POST /api/v1/auth/wallet {"address":"…","nonce":"…","signature":"<base58>","message":"<the same text>"}
# 201 { data: {…}, key: "sk-tr-v1-…" } the wallet account's API key, shown onceWallet-signed requests (X-Wallet-Auth)
Some requests are authorised by a wallet's signature instead of a key: spending the change of a per-call payment, presenting a landed payment, a holder's vote, a host operator's signup and its own host record. They carry X-Wallet-Auth: <base58 address>:<unixSeconds>:<base58 signature>, the signature being the wallet's ed25519 signature over six lines joined by line feeds, with no trailing one:
trellis:wallet-auth:v2
POST
trellis.example
/api/v1/chat/completions
1790000000
<sha256 hex of what the route binds>The method is in upper case. The host is the router's public host as it is configured (with its port, if it has one), in lower case: the same value the sign-in challenge calls domain. The path is the request's path with its query string, as sent. The last line is the SHA-256 of what the route binds: for the chat routes, the canonical JSON (keys sorted, no whitespace) of the body without stream and stream_options; for other JSON routes, the canonical JSON of the body; for a GET, the empty string; for GET /api/v1/hosts/{id}, the string GET /api/v1/hosts/{id}. A signature is valid for five minutes and for one use, and only for that method, that path and that router: the earlier message, trellis:<unixSeconds>:<sha256>, named none of them and is no longer accepted.
Blind tokens
Built, not enabled at launch. The BLIND lane and its tokens are not served on the core launch surface.
On the BLIND lane a call is paid with a blind-signed single-use token (RSA blind signatures, Privacy Pass style) of a fixed denomination: the mint signs a blinded message, so the payment cannot be linked to the call. Tokens are bearer instruments of small fixed denominations redeemable only for inference; a call may cost at most the token's value. The private tokens page runs the purchase in your browser.
Pay with a tokenized stock
Built, not enabled at launch. On the core launch surface a request that carries X-Pay-With is answered 404 not_enabled.
A call that names a token mint in X-Pay-With is paid by an exact-out swap of that token for the USDC it costs, signed by a Swig session key with a per-day cap and batched until at least $1 or 24 hours; the fill must be within 1% of the oracle value, and a token whose Scaled UI Amount multiplier changed in the last 24 hours falls back to credits. A failed swap falls back to prepaid credits, then to 402. The dashboard keeps the mint preference per key under Payments; the SDKs open the session.
Bring your own key
Built, not enabled at launch. Stored provider keys are not served on the core launch surface.
A stored upstream provider key (POST /api/v1/byok) is used for calls routed to that provider and billed by the provider, not by Trellis.
Get USDC on Solana
USDC is a US dollar stablecoin used for prepaid calls. For Trellis deposits it must be USDC on Solana mainnet-beta (CAIP-2 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v. USDC on another network, and any other token that calls itself USDC, does not fund your account here.
Most exchanges let you withdraw USDC directly to a Solana address. Choose the Solana network when you withdraw, send it to a wallet you control (Phantom, Solflare, Backpack or any Solana Pay wallet), and keep a little SOL in that wallet for transaction fees. Then open Payments in your dashboard: the deposit is one trellis_credits::deposit transaction your wallet signs, or a Solana Pay code a wallet app scans.
Deposits are credited once the transaction is finalized, usually seconds. Credits are spend-only: there is no withdrawal. Closing the account returns what is left to the wallet that paid it in; the API key cannot send it anywhere else. USDC deposits are not switched on at trellis.example yet; this guide is for when they are.
Pay by tab
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A tab is the x402 tab scheme: you authorize a ceiling once, the router serves against it, and you pay exactly what you used. open_tab moves the cap into a trellis_tab escrow for a payee until an expiry. Each request then carries a voucher, an ed25519 signature by your session key for the cumulative amount used and a sequence number; nothing goes on chain per call. When the tab closes, the payee posts the highest voucher: it is paid cumulative_used and the rest of the cap comes back to you. If the payee never closes, reclaim after the expiry plus 24 hours refunds everything not covered by the highest voucher the payee posted; it needs nobody's signature. A tab's expiry is at most 30 days from the moment it is opened.
open_tab(payer, payee, mint=USDC, cap, expiry, session_key) // moves cap into the Tab PDA escrow; expiry at most 30 days out
voucher (off-chain) = Ed25519_sign(session_key,
"trellis:tab:voucher:v1" || program_id || tab || created_at || cumulative_used || seq) // 110 bytes
post_voucher(tab, voucher) // payee: records its highest voucher without closing; needs only the tab and the voucher
close(tab, voucher) // payee: verifies the voucher via the Ed25519 program; pays cumulative_used, refunds the rest
reclaim(tab) // anyone: after expiry + 24h with no close, pays the payee its highest posted voucher and the payer the rest
top_up(tab, amount) // payer: before expiry, within the per-tab capWhat a voucher signs
A voucher is the session key's signature over 110 bytes. They start with a fixed domain string, so a voucher is never some other message the key signed. They name the tab program, whose id differs on each cluster, so a devnet voucher is nothing on mainnet. And they carry the tab's created_at, the time the program recorded when open_tab landed: a tab address can be opened again after it is closed (same payer, payee and tab id), and a voucher signed for the earlier opening is worth nothing against the new escrow, even with the same session key. Read created_at from the Tab account once the tab is open; the SDKs do (tabs.resume, fetchTabAccount). The program, the router and the facilitator accept only this form: the earlier 48-byte message (tab, cumulative amount and sequence number alone) is refused. The router answers 402 voucher_wrong_program or 402 voucher_wrong_tab_opening when a voucher was signed for something else.
offset length field
0 22 "trellis:tab:voucher:v1" (ASCII)
22 32 tab program id
54 32 tab address
86 8 Tab.created_at (i64, little-endian, unix seconds)
94 8 cumulative_used (u64, little-endian, USDC base units)
102 8 seq (u64, little-endian)
X-Trellis-Tab: <tab address>
X-Trellis-Tab-Voucher: <base64 of the 110 bytes>.<base64 of the 64-byte signature>A tab can be bound to an on-chain rulebook of the payer's own (a trellis_rules account) when it is opened: open_tab and top_up then also take the rulebook, the rules program's config and the rules program, and the escrowed amount is counted against the rulebook's daily limit. close and reclaim take none of them: the rulebook's limits apply when money is committed, not at settlement, so a rulebook changed or killed after service does not reduce what was vouched. A killed or expired rulebook refuses a new tab or top-up, and the router refuses a call above the rulebook's per-call maximum.
A close does not depend on the payer's accounts. If the payer's USDC account is missing, closed or frozen, the payee is still paid and the payer's share stays in escrow until reclaim delivers it. The payee can post its highest voucher at any time with post_voucher, which needs no token account and no rulebook; a later reclaim pays it that amount. Settlement works from what the escrow holds: anything sent to it by a third party goes back to the payer.
The payee's exposure is bounded: it stops serving when unvouched usage exceeds max(0.25 × last request cost, $0.05). The facilitator verifies and settles tabs non-custodially (payer escrow to payee). Current pricing: no facilitator fee; fee_bps in GET /facilitator/supported says what applies.
The session key
Vouchers are signed by a session key, not by your wallet, so a request does not need a wallet prompt. The tabs page makes one in your browser with WebCrypto, keeps the private half non-extractable in this browser's IndexedDB and shows the public key to give to an SDK; the SDKs can also make their own. Opening a tab, topping it up and reclaiming it are wallet transactions made from an SDK or a script, not from this site.
import { Trellis, signTransaction, sendTransaction } from "@trellis/sdk";
const client = new Trellis({ apiKey: process.env.TRELLIS_API_KEY });
// The session key signs vouchers; the wallet signs open_tab once. Expiry is at most 30 days out.
const sessionKey = await client.tabs.generateSessionKey();
const open = await client.tabs.open({ payer: wallet.publicKey, payee, cap: 20_000_000n, expiry: Math.floor(Date.now() / 1000) + 86_400, sessionKey: sessionKey.publicKey, recentBlockhash });
await sendTransaction(await signTransaction(open.transaction, wallet), { rpcUrl });
// Once it has landed: the session reads the tab's created_at from the chain, because vouchers are signed for it.
const session = await client.tabs.resume({ tab: open.tab, sessionKey, rpcUrl });
// Every call then carries a voucher for the cumulative amount used; the router stops serving if more than
// max(0.25 x last request cost, $0.05) is unvouched, and says how much to vouch for (402 voucher_required).
const voucher = await session.voucher(12_300n);
const reply = await client.chat.completions.create({ model, messages }, { headers: voucher.headers });x402 facilitator
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Trellis runs an x402 facilitator for Solana: GET /facilitator/supported, POST /facilitator/verify and POST /facilitator/settle, for the schemes exact and tab on solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, asset USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v). It is non-custodial: it never holds funds, and settlement goes from the payer (or the payer's tab escrow) straight to the payee. The facilitator's relay key pays the Solana network fee as fee payer and takes nothing out of the settled amount. It signs only above its balance floor and within budgets per payer, per seller, per source address and in total (over any minute and any 24 hours); past a limit settle answers 429 rate_limited, and a payer whose sponsored payment failed after it was sent is not sponsored again for 30 days (403 payer_not_sponsored). A settlement is simulated before the relay signs, and one that would fail is not sent.
On Trellis’s own per-call path the rule differs, and is stated under Payments: a per-call payment has a minimum size (0.03 USDC by default) and the router passes the network fee of that payment on to its payer at cost, as its own line (network_fee on the receipt, quoted as network_fee_max_usdc). That is cost recovery, not a markup; GET /api/v1/status shows lamports paid beside USDC recovered.
GET /facilitator/supported
{ "kinds": [
{ "x402Version": 2, "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "extra": { "feePayer": "<relay address>" } },
{ "x402Version": 2, "scheme": "tab", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "extra": { "program": "<trellis_tab program id>", "feePayer": "<relay address>", "maxCapUnits": "…" } } ],
"fee_bps": 0, "fee_waiver_until": "…", "networks": ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"] }verify takes a payment payload and the seller's payment requirements and answers { isValid, invalidReason?, payer }; settle submits the transfer and answers { success, transaction, network, payer }. A (payer, nonce) pair settles once: a replay returns the earlier result. The facilitator charges no fee; fee_bps and fee_waiver_until say which applies now.
The facilitator is open to any seller, not only Trellis; the tab scheme is published as a draft extension to x402. Sellers listed in the tool market through it appear in search without a canary.
Early credit
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
USDC deposits into the trellis_credits program are credited once Solana finalizes them, usually seconds, so early credit rarely matters there; it exists for routers that still take priced deposits through an escrow account. Fast escrow credit is switched on at trellis.example (self-hosted routers: FAST_CREDIT_ENABLED, default false). Eligible escrow deposits can receive spendable credit after FAST_CREDIT_CONFIRMATIONS sequencer confirmations (default 10). Outstanding early credit is capped at $25 per account and $250 across the router by default, configurable with FAST_CREDIT_ACCOUNT_MAX_USD and FAST_CREDIT_GLOBAL_MAX_USD. Escrow prices are fixed when early credit is issued; the remainder waits for the configured chain finality point and confirmation floor. Early credit buys calls while settling, usually around 20 minutes, but timing varies. A chain reorganization reverses early credit; a negative balance blocks further spending until covered.
Deposit countdown and credit notices
Follow your USDC deposit in Payments. When the chain supplies enough timing information, the panel shows about how many minutes remain until finality. It refreshes automatically. Timing can change; when it is unknown, the panel shows the current stage. Early credit can still be reversed by a chain reorganisation.
GET /api/v1/escrow/deposits and GET /api/v1/credits/deposits require an active bearer key. Deposits include nullable expected_final_at, an approximate ISO timestamp derived from the deposit block and current chain head/finality progress. The existing account panel polls every five seconds; an expired estimate never means the transfer is final.
DEPOSIT_PINGS_ENABLED defaults to false. When enabled on the worker, include deposit-pings in WORKER_JOBS. It reads up to 100 newly credited deposits from the last day per pass, including early credits, and adds one inbox notice per deposit. The inbox uses the existing account access rules; ordinary and session keys cannot read these account notices.
Existing Telegram account links can receive the token amount, credited amount and current account balance when Telegram linking and the bot are configured. The link is checked again before sending. A permanent delivery marker prevents repeat sends; interruption or failed delivery can lose a message. Linking later does not replay older deposits. The inbox remains available even if Telegram delivery fails. Credit notices are not switched on here yet.
Balance runway and alerts
See how long your balance might last at your last seven days of charged spending. Home and the account strip show the estimate when there is spending to compare. In Money, an owner can choose an amount for a low-balance alert. Alerts are not switched on yet.
Built, not enabled at launch. The runway estimate is not served on the core launch surface. The low-balance alert is.
GET /api/v1/account/runway requires the same active Bearer key as credits. Account-scoped keys see settled account balance and account spending; session keys see their remaining budget and their own spending. Inference-only keys cannot read it. The response contains numeric balance_usd, spend_7d_usd, per_day_usd (charged spend divided by seven), and days_left (balance divided by that pace, rounded down; null when spend is zero).
Spend counts posted usage and paid-tool debits during the preceding seven days, by settlement time. Refunds do not reduce charged spend; deposits, withdrawals and token purchases are excluded. Open holds do not reduce the settled balance used here. This is a pace estimate, not a promise of future spending.
GET /api/v1/account/low-balance returns low_balance_usd (nullable) and enabled. PATCH /api/v1/account/low-balance accepts that nullable amount from zero to one million dollars. Both require an owner key; sessions and inference-only keys are excluded. Null clears the setting. Edits answer 403 when LOW_BALANCE_ALERTS_ENABLED is off (default false).
When enabled, the low-balance-alerts worker checks every five minutes, records one inbox item while settled balance is below the threshold, and attempts a Telegram message through any authorized account link. It re-arms only when a check sees balance strictly above the threshold; equality does neither. Changing the threshold starts a new check. The inbox record and crossing claim are committed before Telegram delivery. Telegram failures are not retried, and an interruption can leave an inbox item without a message. Earlier inbox items stay. The funding link uses the configured SITE_URL.
Make-good refunds when a call fails you.
Built, not enabled at launch. Make-good refunds are off by default. On the core launch surface an issued refund is a credit on your balance, and refunds paid back on chain are not served. What a call costs when it ends early is under Payments.
Not switched on at trellis.example yet. Self-hosted routers can enable MAKEGOOD_ENABLED (default false). While it is off, nothing on this page happens and billing is unchanged; GET /api/v1/status reports makegood.enabled either way.
Refund rules (current policy)
These are the rules the router applies today; they describe current behaviour and can change. Each rule is decided from facts the router records when it serves (or fails) the call: error classes, token counts, prices, the lane and the attestation result. There is no claim form and no judgement call. A call meets at most one rule; the largest refund wins.
| Rule | When | Refund |
|---|---|---|
upstream_failure | A per-call payment (x402 or CallPay) bought a request that no provider served: every attempt failed, at least one with an upstream 5xx, timeout, connection failure or broken stream, and none rejected the request itself. | The full payment, sent back on-chain. |
fallback_price | The first provider tried for the model failed, and the call went to a provider that costs more for the same tokens (route_explain.reason is fallback). | The price difference for the tokens of the call. |
truncated_stream | The upstream stream ended or broke before any finish_reason. A client that hangs up is not made good. | The price of the billed output tokens that were never delivered. A stream billed only for what it delivered has nothing to refund. |
structured_output | With trellis.json_check repair, the repair answer still does not parse as JSON. Valid JSON that misses the schema does not count. | The full charge for the repair call. The first call stays charged. |
unattested_lane | An attested-lane (or :private, or disclosure none) call settled without a fresh attestation, or with an attested gateway receipt that does not show an attested upstream. Routing already fails closed; this is the second check. | The full charge, plus a strike against the host. |
The hourly settlement job issues a refund about a minute or more after the call. It writes a ledger line of kind refund linked to the generation, signs a refund receipt of kind refund that names the original receipt (original_receipt_id), and queues a refund.issued webhook (reference: the refund id, status: the rule) for destinations that subscribe to it. The refund appears in Activity as "Make-good refund" with its receipt, in the refunds total of the monthly statement, and in GET /api/v1/refunds. GET /api/v1/receipts/rf_… returns the signed receipt; check it with POST /api/v1/receipts/verify or on /verify.
{
"v": 1,
"kind": "refund",
"id": "rf_…",
"issued": "2026-10-02T12:00:00.000Z",
"router": "https://trellis.example",
"original_receipt_id": "gen-…",
"generation_id": "gen-…",
"rule": "fallback_price",
"amount": "0.000184",
"charged": "0.000412",
"settlement": "credit",
"provider": "provider-id",
"strike": false,
"evidence": {
"served_provider": "…",
"planned_provider": "provider-id",
"planned_error": "http_5xx",
"served_cost": "0.000412",
"planned_cost": "0.000228"
}
}A refund is never more than the ledger charged for that call (for an unserved paid request: the payment still unspent on the wallet account), and a call is refunded at most once. One refund record exists per call or payment, it is decided once under a row lock, and its ledger references are unique, so a retried or concurrent settlement run changes nothing.
Calls paid on-chain per call (x402 or CallPay) are refunded on-chain. A served call's refund is credited and moved, in the same transaction, into an obligation to the paying wallet (an unserved paid request's unspent payment is moved the same way); the makegood-payouts worker job sends each wallet one USDC transfer per hour for all it is owed, from the treasury key MAKEGOOD_REFUND_PRIVATE_KEY. Only whole USDC units go on-chain; any remainder below one unit stays as wallet change. Each transfer is signed and stored before it is broadcast and is only ever resent as the same transaction, so a crash cannot send it twice. Without the key the job refuses to run and the refunds stay owed: makegood.onchain in the status and onchain.status in GET /api/v1/refunds show what is owed and what has been sent. With sanctions screening on, a listed wallet is held, not sent.
A refund caused by a network host is recorded as host slashing evidence for review when host bonds are on; it is never proposed automatically. An attested-lane refund also counts as a host strike in the status.
Limits: blind-token calls name no account, so they are not refunded. Encrypted chat (E2EE) is not covered, because the router does not see its tokens. A failover price difference is not computed when either provider uses your own key, or when the first-choice provider is no longer listed. Refunds do not restore a key's spending budget. Refund receipts are v1 (Ed25519 over canonical JSON) and are not yet anchored on-chain.
Statements and account export
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Monthly statements are switched on at trellis.example. Self-hosters enable STATEMENTS_ENABLED (default false) to expose GET /api/v1/statements/:yyyy-mm. Supply a bearer API key; management and owner/admin keys read account totals. Ordinary and session keys read only their own attributed movements, labelled scope: key. This is the same scope rule as Activity.
GET /api/v1/statements/2026-09?format=json
Authorization: Bearer <your-key>The response is { data: { payload, alg: "Ed25519", key_id, sig } }. The existing receipt key signs canonical JSON. Verify it in Verify by pasting or dropping JSON. The signature establishes what the router signed; it does not independently prove ledger completeness.
Amounts are exact USDC decimal strings. Opening + deposits + refunds − usage − separate fees + other changes = closing. Each usage grouping sums to charged ledger usage. Month boundaries use UTC, usage follows settlement time, and call counts follow generation time. Missing attribution appears as null. Balances exclude holds and external wallet escrow; embedded usage fees are not added again. Key-only balances are attributed sums, not the account’s shared balance.
Invalid months return 400. Months before account creation or in the future return 404. The current month is marked so_far: true. Disabled statements return 404. Responses use Cache-Control: no-store; later ledger entries can change an earlier statement.
Open Statements under Billing for signed JSON or a printable view; use the browser’s Save PDF option. Open Export your data under Settings for one browser-built bundle of readable account records with progress and cancel. Existing API scopes and retention apply. Approvals have an existing 100-per-status cap; unavailable sections and per-agent access limits are listed. No key secrets are included. Chat history lives in the browser and is exported from Chat. Read What we keep for what the router retains beyond this bundle.
Proof pack
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A proof pack is one JSON file for a date range that anyone can check with no network. It holds the calls in range with their signed receipts and Merkle paths, the refund receipts issued in range, the signed monthly statements covering those dates, the router's published receipt keys and a manifest the router signs over exactly which receipts it listed. Receipts carry hashes, token-count buckets and amounts; the pack holds no prompt or answer text.
It follows the statements feature: self-hosters enable STATEMENTS_ENABLED (default false), and with it off the route answers 404. Key access is the statement and Activity rule: management and owner/admin keys read the account; ordinary and session keys read only their own calls and refunds, labelled scope: key. Inference-only keys cannot read it.
GET /api/v1/proof-pack?from=2026-09-01&to=2026-09-30
Authorization: Bearer <your-key>from and to are UTC calendar dates, both included, at most 31 days apart; a longer range answers 413 and a malformed one 400. One file holds up to 2,000 calls under at most 200 anchor roots. A larger range sets truncated: true and a next_cursor; pass it back as cursor with the same dates for the next part. Each part verifies on its own. Ten packs per key per minute; then 429 with Retry-After. GET /api/v1/proof-pack/limits answers with these caps and the key's scope.
The response is { data: { type: "trellis.proof-pack.v1", range, scope, calls, lane_report, decision_tags, refunds, statements, keys, manifest, next_cursor, verify } }. Each call's receipt is the object GET /api/v1/receipts/:id serves, so it can also be pasted into Verify. keys is the content of /.well-known/trellis-receipt-keys.json at download time.
Check it on Verify or with the script below. On Verify, the file is read in your browser and never uploaded. A GET request loads Trellis’s published receipt keys; signatures, paths and totals are checked on your device. The script uses the keys in the file with no network; compare them with the published key list yourself.
node scripts/verify-proof-pack.mjs trellis-proof-pack-2026-09-01-to-2026-09-30.jsonThe verifier needs Node 18 or later and nothing else. It checks that each key id matches its key bytes; every v1 and v2 receipt, refund receipt, statement and the manifest signature against the keys in the file; each receipt's anchor leaf; every Merkle path present; each statement's arithmetic; that the lane report adds up and matches the calls, with each call's lane, provider and model matching its signed receipt; that decision_tags names exactly the decision tags the signed receipts carry; and that the manifest lists exactly the receipts, statements, keys, lane report and decision tags in the file. It exits 0 only when every check passes.
node scripts/verify-proof-pack.mjs trellis-proof-pack-2026-09-01-to-2026-09-30.json --intent order.jsondecision_tags has one row, { id, decision_tag }, for each call whose receipt carries a decision tag. The file holds the hashes, never the orders. With --intent (repeatable) the verifier hashes each order file as the decision-receipt helpers do and names the calls whose signed receipt carries that hash; an order no receipt carries fails the run.
A Merkle path shows a receipt sits under a root. That the root was posted on chain is not shown by the file: a proof's status, tx and mode, and the anchorer keys listed in the file, are the router's own statement, and neither Verify in the browser nor the offline run checks them against the chain. To check, run the script against a Solana RPC with settings of your own: the key document you fetched from the router, or the anchor mode, network and anchorer key you pinned.
curl -s https://<router>/.well-known/trellis-receipt-keys.json > keys.json
node scripts/verify-proof-pack.mjs trellis-proof-pack-2026-09-01-to-2026-09-30.json --rpc <solana rpc url> --keys keys.jsonA root counts only when its transaction is finalized, was signed by the anchorer key in your settings, landed within the lateness bound after its hour closed (six hours unless the key document says otherwise), and is the earliest root that key signed for the hour. When the RPC cannot show the anchorer's history back to the start of the hour the answer is unknown and the script exits non-zero; it never assumes. Receipts from the most recent hour have no path until their hour is rooted. The manifest signature is the router's statement of what it listed, not an independent audit of its records.
Download one from Statements under Billing. Nothing is stored for a pack beyond a per-key rate-limit counter; What we keep lists it.
Lane report
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A lane report shows where your calls ran over a month or any range of up to 31 days: calls and spend on each lane (public, attested and unlinkable), the share that ran on proven hardware, and, for the attested and unlinkable lanes, each provider and model with a link to that provider's hardware evidence. Both of those lanes admit only endpoints whose fresh hardware attestation the router verified. An endpoint is one of two kinds: an attested gateway, whose signed receipt says what it verified about the model server behind it, or a Graft host, whose measurements and model digest the router pins itself; each call's receipt says which kind served it (Lanes). The lane counted is the one each call's signed receipt records.
It follows the statements feature, which is switched on at trellis.example: self-hosters enable STATEMENTS_ENABLED (default false), and with it off the route answers 404. Key access is the statement and Activity rule: management and owner/admin keys read the account; ordinary and session keys read only their own calls, labelled scope: key. Inference-only keys cannot read it. Thirty reports per key per minute; then 429 with Retry-After.
GET /api/v1/lane-report?from=2026-09-01&to=2026-09-30
Authorization: Bearer <your-key>from and to are UTC calendar dates, both included; a longer range answers 413 and a malformed one 400. The response is { data: { type: "trellis.lane-report.v1", range, scope, totals, lanes, proven, providers, not_recorded } }:
totals: calls and spend in USDC, an exact decimal string.lanes: one row each for public, attested and unlinkable, with calls, spend,share_of_callsandshare_of_spend(four decimal places, rounded half up; null when there is nothing to divide). Calls whose receipt records no lane are a row withlane: null.proven: the attested and unlinkable lanes together, with the same shares.providers: one row per lane, provider and model on those two lanes, withevidence_url(the provider's record on Verify) andattestation_url(GET /api/v1/attestation/:provider). Proof-time shows how recently each provider's hardware was verified.
Calls are counted by call time with the same rows as Activity and the proof pack. Spend is the amount charged for each call; statements group charged usage by settlement time, so the two can differ near a month's edge. The evidence link shows the provider's current record and its history; each call's receipt carries the attestation reference it was served under. Calls paid with a blind token name no payer, so they cannot be attributed to an account and are not in a report.
Two things are not recorded per call and so are not counted: whether a request's lane came from the key's default route (the X-Trellis-Default-Route response header says so at the time), and requests refused because no endpoint on a lane could take them. not_recorded says so in the response.
Every proof pack carries the same report for the calls in its file, as lane_report, inside the signed manifest. scripts/verify-proof-pack.mjs recomputes it from the calls, checks the totals, lanes, shares and provider rows add up, and checks each call's lane, provider and model against its signed receipt. See it under Statements under Billing as Where your calls ran. Nothing is stored for a report beyond a per-key rate-limit counter; What we keep lists it.
Routing
A request names a model and, optionally, how to choose among the providers that serve it. Model ids are author/model, with the suffixes :nitro (sort by throughput), :floor (sort by price) and :free. models is an ordered fallback list tried when the first model cannot be served.
The provider object narrows the choice: order, only and ignore name providers; allow_fallbacks (default true) lets the router move down the list when a provider fails without producing tokens (a 5xx, a refused or reset connection, a stream that breaks before any content, an empty 200 that reports no usage), and such an attempt is not charged; when the router’s own timeout cuts off a provider that had accepted the request, the call ends there with 504 provider_timeout and is charged as Calls that end early says; require_parameters keeps providers that do not support a parameter you sent out of the running; quantizations, max_price (per million prompt and completion tokens), sort (price, throughput or latency), data_collection and zdr route on the provider’s documented data handling; lane is the floor described under Lanes.
Among the candidates left, the router drops any provider with an outage in the last 30 seconds and weights the rest by uptime × quality × attested_bonus / price² (GET /api/v1/status reports the formula it is running). A request never falls back off an attested lane. A saved route stores a provider object and a model list under a name, and a key can carry a default route. With route explanations on, the receipt says which providers were eligible and why one was chosen (Why this route?).
curl https://<router>/api/v1/chat/completions \
-H "Authorization: Bearer $TRELLIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen/qwen3-32b",
"models": ["deepseek/deepseek-v3"],
"provider": { "lane": "attested", "sort": "price", "max_price": { "completion": 2 }, "allow_fallbacks": true },
"messages": [{ "role": "user", "content": "Hello" }]
}'Lanes
A lane says what the router may do with a request. Set it with provider.lane in the body or the X-Trellis-Lane header; a key or a saved route can carry a default. A lane is a floor: the router never serves a request below the lane it asked for, and says why when it cannot (no_attested_endpoint, lane_requires_anonymous_auth). The lane that served a call comes back in the X-Trellis-Lane header and in the signed receipt.
| Lane | Path | Who can run it | Payment |
|---|---|---|---|
public | TLS to the router, then to any provider | Any provider | API key, credits, per-call payment or blind token |
attested | TLS to the router, then to an enclave whose attestation the router verified recently | Attested providers only | API key, credits, per-call payment or blind token |
unlinkable | Oblivious HTTP through an independent relay, or Tor to the router’s onion service; then to an attested enclave | Attested providers only | Blind tokens only; an API key or a wallet is refused |
Two kinds of provider serve the attested and unlinkable lanes. An attested gateway is a provider that runs the confidential hardware and exposes an attested, OpenAI-compatible endpoint: the router verifies the gateway’s attestation on every attestor pass, forwards the request (or ciphertext, on the encrypted chat path) and pays per token at the gateway’s own price with no markup, so the lane costs nothing while it is idle. A Graft host is an operator’s own confidential VM running the Graft sidecar, whose measurements and model digest the router pins itself (Run a provider). The receipt says which kind served a call: a gateway call carries the gateway’s own signed receipt and its claims as upstream_attestation.
The two do not prove the same thing. With a gateway, the proof covers the gateway enclave and what its receipt asserts about the model servers behind it, not a container Trellis controls. The router does not appraise the gateway’s source itself: in production it attests a gateway only against a measurement allow-list its operator configured, naming both the MRTD and the RTMR3 of a release the operator accepted, and a gateway with no such list, or on a release that is not listed, fails attestation. It checks platform patch level (TCB status) only when a DCAP or Intel Trust Authority verifier is configured, and takes model-weights provenance as the gateway reports it. A gateway that fails attestation is dropped from the lane until it verifies again.
On every lane the router reads ordinary chat text in memory to route and bill it; what it does not do is keep it. Only the encrypted chat path forwards ciphertext. The lane report counts how many of a key’s calls ran on each lane.
Unlinkable lane over Tor
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
The unlinkable lane hides who is asking from the router. The client either sends through an Oblivious HTTP relay run by another operator (GET /api/v1/ohttp/keys publishes the gateway key configuration, /api/v1/ohttp/key-list the signed history of it) or reaches the router’s Tor onion service, where Tor takes the relay’s place: an onion service is never given the client’s address. Either way the request is paid with a blind token; an API key or a wallet is refused on this lane, because both would name the payer.
What stays visible: request size and timing, the model asked for and the destination host. An observer watching both the client’s entry into Tor and the router can match them by timing, and requests sent on one Tor circuit can be linked to each other. The private proxy sets up a Tor client, buys tokens and sends through the onion service in one command. Both paths are off by default on a self-hosted router; GET /api/v1/status reports lanes.unlinkable.available and onion.address.
Make any AI app private in one command.
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
trellis-private is a small program that runs on your own computer and looks like the OpenAI API at http://127.0.0.1:8788/v1, so any app that lets you set a base URL can use it. Every call it receives is rebuilt from scratch and sent to Trellis’s onion service through your own Tor client, on the unlinkable lane, and paid with a blind token. It is Apache-2.0 licensed, has no dependencies to install, and is one file: node private.mjs.
Get it, and check it.
The program is one file, 180,221 bytes, version 0.1.0, not minified, so you can read it before you run it. Download it, then compare its SHA-256 with this one:
curl -fsSLO https://trellis.example/private.mjs
shasum -a 256 private.mjs # or: sha256sum private.mjsExpected SHA-256: f039b05b2d68fe500eae8c8621da12ad8b56b2d298b08186848611342c10c751
The hash and the file come from the same site, so this catches a damaged or swapped download but not a compromised site. To check the file against the source, build it yourself with Bun (bun packages/private/scripts/build.ts in the repository writes the same bytes); a check in the repository rebuilds it and fails if the served file differs. Downloading from the clearnet shows the site your address, though nothing about what you will do with the file. To avoid even that, fetch it through Tor: curl --proxy socks5h://127.0.0.1:9050 -fsSLO https://trellis.example/private.mjs. It needs Node 20 or later. It includes the two libraries it uses, with their licences, at the top of the file.
Four steps.
# 1. A Tor client on this machine. Skip this if Tor Browser is open: it listens on 127.0.0.1:9150.
brew install tor && brew services start tor # Debian and Ubuntu: sudo apt install tor
# 2. Buy blind tokens with an API key that has credits. The purchase goes over Tor too.
export TRELLIS_API_KEY=sk-tr-v1-…
node private.mjs buy --count 20
# 3. Start the proxy. It refuses to start unless Tor answers.
node private.mjs start
# 4. In the app's shell, or its settings: point it at the proxy.
export OPENAI_BASE_URL=http://127.0.0.1:8788/v1
export OPENAI_API_KEY=trellis-private # any non-empty value; the proxy discards itOn the first run it asks the router for its onion address at its public name, through Tor (a Tor exit connects, your address never does), checks that the address is a valid version 3 onion address, saves it in ~/.trellis, and uses it from then on; --onion gives one yourself. Tokens are kept in ~/.trellis/tokens.json, a file only you can read (mode 0600) in a directory of mode 0700. TRELLIS_HOME moves them.
What it does to each call.
- Listens on 127.0.0.1 only, and refuses a request whose Host is not 127.0.0.1 or localhost, or that carries the Origin of a web page, so a page in your browser cannot spend your tokens. On a shared machine, --local-key makes the app present a secret.
- Sends a fixed set of headers written by the proxy: Host, Accept, Content-Type, Content-Length, Connection, Authorization: PrivateToken and X-Trellis-Lane: unlinkable. Nothing the app sent is copied: not its API key (an OpenAI key in OPENAI_API_KEY is discarded, never forwarded), its user agent, cookies, referrer, SDK and tracing headers, or forwarded-address headers. The body goes through as it came, except that the OpenAI
userfield, which names an end user, is removed. - Uses one token per OpenAI call, or a budget-covering set for Messages, taken out of the file before the call is sent, so it is never sent twice. A token the router refuses as spent or invalid is dropped and the call is tried with the next; a refusal for another reason (no attested provider for the model, a rate limit, a token too small for the request) keeps the token. A call sent and then lost is marked unconfirmed and its token is not used again.
- Puts each call on its own Tor circuit, with a fresh SOCKS user name, so two calls are not carried together. --shared-circuit reuses one, which is faster.
- Has no other way out. The only address it ever connects to is your Tor client’s SOCKS5 port (127.0.0.1:9050, or 9150 for Tor Browser, or --socks), and it asks for the onion service by name, never resolving it. It refuses to start unless a Tor client answers and the onion service reports the unlinkable lane available over Tor. If Tor stops, calls fail with 502; nothing falls back to a direct connection. When the tokens run out, calls fail with 402 and the command to buy more.
curl http://127.0.0.1:8788/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"<a model from /v1/models>","messages":[{"role":"user","content":"Hello"}],"stream":true}'
# what the router receives, in full:
# POST /api/v1/chat/completions Host: <onion address>
# Accept, Content-Type, Content-Length, Connection: close
# Authorization: PrivateToken token=<one token>
# X-Trellis-Lane: unlinkableWhich apps.
It serves POST /v1/chat/completions (streamed or not), POST /v1/embeddings and GET /v1/models, which lists the models an attested provider can serve on this lane. Point any OpenAI-compatible SDK, command-line tool or editor extension that lets you set a base URL at http://127.0.0.1:8788/v1 with any non-empty API key. Cursor has an Override OpenAI Base URL setting under Settings, Models; Cursor may send requests from its own servers, which cannot reach an address on your computer and would see your prompts, so check that your version calls the API from your computer before relying on it. Claude Code and the Anthropic SDKs can use POST /v1/messages with blind tokens; see Claude Code, unlinkable. The Responses API is not supported by this proxy.
Tokens: cost and expiry.
| Size (--denomination) | Face value | Fits |
|---|---|---|
| 1000 | $0.002 | short answers from inexpensive models |
| 10000 (default) | $0.02 | most chat calls |
| 100000 | $0.20 | long answers, or expensive models |
A token payment pays for one call, whatever the call costs; the rest of its value is not refunded. Messages calls can combine tokens to cover their estimated budget. The router holds the worst case for a call against the token’s face value. That worst case is a bound, not an estimate: the prompt counted at its UTF-8 bytes plus a fixed template allowance (several times a tokenizer’s count), and max_tokens or, when you send none, the model’s output limit (16,384 tokens when the catalog lists none), at the model’s price. If that is more, it answers 402 token_value_too_low and does not spend the token: lower max_tokens or buy a larger size. Face values are those of the router’s current keys; buy prints what you paid and status what you hold. Tokens expire at the end of the router’s redemption window, one to two weeks after they are bought; buy prints the time and status shows the next expiry, so buy what you will use soon. A purchase names your API key’s account; a token later shown to the router cannot be connected to it, but it hides only among the tokens of the same size bought in the same week, and buying one and spending it at once links the two by time.
node private.mjs status
Tor: reachable at 127.0.0.1:9050 (Tor daemon)
Onion service: <56 characters>.onion answers (3.1 s)
Unlinkable lane: available over onion, <n> models
Blind tokens: 18 usable (18 x 10000 units; $0.36 of face value)
The soonest expiry is 2026-10-08 00:00 UTC.Other limits of what this hides: someone who can watch both your connection into Tor and the router’s side can match calls by timing; the size and timing of a call are visible to the router; and a provider that receives a prompt that names you knows who you are. The lane is the one described above as the unlinkable lane over Tor. The tokens are Privacy Pass tokens (RFC 9578) made with RSA blind signatures (RFC 9474), the same ones buyTokens in @trellis/client/blind buys.
Claude Code, unlinkable.
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Claude Code can use the proxy’s Anthropic Messages API over Tor, paid with blind tokens. Start Tor on your computer, download and check private.mjs, and buy tokens with a funded Trellis key. The purchase uses the key; inference sends only tokens.
export TRELLIS_API_KEY=sk-tr-v1-…
node private.mjs buy --count 20 --denomination 10000
node private.mjs start
# Optional: --shared-circuit reuses a Tor circuit within this proxy session.
# If the operator uses a lower token cap: --max-tokens-per-request <cap>In another shell, list the currently available attested models through the proxy. Choose models with reliable tool calling and enough context for your code. Replace both model values below with ids returned by that list. The proxy discards the client’s API key, metadata and identifying headers.
curl http://127.0.0.1:8788/v1/models
export ANTHROPIC_BASE_URL=http://127.0.0.1:8788
export ANTHROPIC_API_KEY=trellis-private
unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_MODEL='<attested model id from the list>'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='<attested model id from the list>'
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claudePOST /v1/messages streams the Messages events, tools, refusals and receipt headers from the router. POST /v1/messages/count_tokens is answered on your computer with the router’s own counting rule: no network call and no token payment. The figure is the router’s prompt bound, the one its hold is priced at: the UTF-8 bytes of the text and tool schemas plus fixed template allowances. It is an upper bound, several times a model tokenizer’s count for English text. A count request that carries an image is refused with a 400 here, because an image is bounded only by the per-image limit a model declares.
Before inference, the proxy computes the router’s bound on the input (its UTF-8 bytes plus template allowances, at the dearest input price the model lists; an image needs a model that declares a per-image token limit, or the call fails with no tokens spent) plus max_tokens at prices fetched over Tor from GET /api/v1/models?lane=unlinkable, cached in memory for one minute, including the request fee, reasoning price and royalty. It chooses the least total face value covering that budget, breaking ties by fewer tokens, up to 16 by default. Every selected token is spent for that one request; unused value is forfeited. A changed price or a more expensive routing candidate can cause 402 token_value_too_low without spending the set. Lower max_tokens or buy larger denominations if your available set cannot cover a call.
The header extension is Authorization: PrivateToken token=A, token=B, with each value a base64url Privacy Pass token. Single-token headers and receipts retain their existing format. Sets verify and reserve atomically; receipts add only token_count, token_key_ids and nullifiers as payment identifiers. Those tokens become linked to one request, never to their purchase. A refusal before service releases the whole set; a lost response leaves the sent set unconfirmed on your computer.
Operator configuration: TRELLIS_FEATURE_BLIND=false, UNLINKABLE_VIA_ONION=false and BLIND_MULTI_TOKEN_ENABLED=false by default. Enable them with the existing onion ingress and attestation configuration; ONION_ADDRESS and ONION_PROXY_SECRET must be configured. BLIND_MAX_TOKENS_PER_REQUEST defaults to 16 (allowed range 1–64). BLIND_UNIT_PRICE_USD defaults to 0.000002 per unit; denominations are 1000, 10000 and 100000. Tor onion access and blind tokens are switched on at trellis.example. Downloading the proxy changes no operator configuration.
Tor adds latency, and its first connection can take a minute. Each call uses a fresh SOCKS identity by default; --shared-circuit reuses one for this proxy process, which can reduce setup latency and makes calls share a network circuit. Claude Code’s effectiveness depends on the selected open model and its tool support.
Blind tokens
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A blind token is paid access that the router cannot link to a purchase: Privacy Pass tokens (RFC 9578 type 0x0002, blind RSA signatures per RFC 9474). GET /api/v1/blind/keys lists one 2048-bit issuer key per denomination (1,000, 10,000 and 100,000 token-units) per weekly epoch, published before the epoch starts. POST /api/v1/blind/purchase debits the key’s credits and returns one blind signature per blinded message; the client blinds the inputs and unblinds the signatures locally, and the router stores counts only, never the blinded messages or the tokens. Spending a token on the unlinkable lane reveals nothing about which purchase it came from.
The blind tokens page runs the flow in the browser and keeps the tokens in a file you hold; the private proxy buys and spends them from the command line. Blind tokens are present only when the router enables them (GET /api/v1/status reports it); the protocol specification (0003) describes the e-cash format that will replace this one.
End-to-end encrypted chat (attested gateway)
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
The dedicated POST /api/v1/e2ee/chat/completions adapter forwards encrypted message content unchanged to the attested confidential-AI gateway. It is switched on at trellis.example. It is off by default in the open-source router until its operator sets E2EE_PASSTHROUGH_ENABLED. Ordinary chat routes on every lane still read request text in router memory.
Client encryption ends inside the attested gateway enclave. The gateway restores content and forwards it to the serving workload over a separate confidential channel. This is not client encryption directly to a GPU. The router sees the model, roles, message count, content sizes, timing, public keys, nonce, timestamp, response framing, finish reasons, usage and API key or blind-token authorization. A correctly encrypting client keeps message content and its private key out of the router.
The JavaScript SDK exports e2eeChat(body, options) and client.e2eeChat(body, options). Supply model, text messages, stream, an optional max_tokens ceiling (default: 512), and a required verifyAttestation callback. Set the options lane to unlinkable when using Tor with blind tokens. The helper fetches GET /api/v1/e2ee/attestation?nonce=… with its own fresh challenge, checks the keyset digest, quote report-data binding, expiry and debug bit, then encrypts each content field using X25519, HKDF-SHA256 and AES-256-GCM with canonical AAD. Your callback must verify the TDX quote signature and Intel collateral, replay and appraise the measured event log, enforce accepted measurements, and assess the deployment and key custody. A router boolean is never evidence.
Both buffered JSON and SSE are supported. The helper verifies every encrypted field tag, then the gateway’s Ed25519 receipt over the exact response wire bytes and restored request. Decrypted streamed chunks remain provisional until iteration finishes and the complete signed receipt verifies; stopping early does not establish a complete answer. A missing sentinel, wrong key, field mutation, reordering or truncated response fails closed. There is no plaintext fallback.
Only exact model identifiers offered by the attested gateway provider are admitted, on the attested lane or the unlinkable lane over Tor with blind tokens. Gateway-verified routing and zero data retention are required. Tools, files, search, structured content, aliases, presets, caching, content policies and unknown fields are refused. Key balances and blind tokens are supported; wallet and pay-with authorization are refused. The router validates ciphertext framing; it cannot determine the plaintext modality or prove that an arbitrary caller actually encrypted a hex string. The router limits envelopes to 1 MiB and responses to 32 MiB. The SDK retains bounded encrypted wire bytes until it can verify the complete receipt.
Before forwarding, the router places a hold priced from a conservative byte-based input bound plus max_tokens. Ciphertext length is a reservation bound, not observed token usage. Billing trusts the gateway’s reported token counts under the same provider trust model as ordinary chat. On completion or truncation, reported usage settles the charge and releases the unused hold; without reported usage, the hold is charged. Blind-token overages are capped at the hold and unused token value follows the existing forfeiture rules. A provider refusal before a response releases the hold and blind-token claim. A process failure can leave a hold for the existing expiry recovery; expiry recovery cannot reconstruct unseen provider usage.
The router’s signed receipt marks encrypted content and hashes the exact forwarded ciphertext bytes. It keeps counts or billing bounds, cost, timing, byte counts, completion state, gateway keyset reference and response-verification status, with key linkage or blind nullifiers. It keeps no message ciphertext, plaintext, private key or replay nonce. The router cannot reproduce the gateway’s restored plaintext request hash and records that check as false. The SDK can check that hash. Receipts are public by id; hashes of low-entropy plaintext in gateway receipts may permit guessing.
Production startup requires PROVIDERS_FILE to declare the live HTTPS TDX provider, its attestation URL and credential reference, plus the matching configured database provider. Forwarding requires fresh verified gateway attestation and pinned TLS. No existing production independence guard is relaxed. Operators must supply the provider credential, acceptable attestation policy and compatible gateway; repository validation does not establish an encrypted exchange with a live account.
V2 does not pad sizes, hide billing or network metadata, encrypt all clear response metadata, or provide forward secrecy against later compromise of a reused recipient key. Browser-delivered client code must be independently trusted. The gateway’s attested status does not by itself establish GPU attestation. Upstream and GPU claims are gateway assertions, authenticated by its signed receipt and, when cited, a content-addressed session. The proof covers the gateway enclave, not a container Trellis controls: the router does not appraise the gateway’s source itself: in production it attests a gateway only against a measurement allow-list its operator configured, naming both the MRTD and the RTMR3 of a release the operator accepted, and a gateway with no such list, or on a release that is not listed, fails attestation. It checks platform patch level (TCB status) only when a DCAP or Intel Trust Authority verifier is configured, and takes model-weights provenance as the gateway reports it. On a Graft host the router pins the measurements and the model digest itself (Lanes). The client can pin appraised session identifiers.
Encrypted chat is switched on at trellis.example.
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
The dedicated POST /api/v1/e2ee/chat/completions adapter forwards content encrypted on the client to the attested gateway enclave. A correctly encrypting client keeps message content out of the router. Encryption ends at that gateway, which forwards restored content to the serving workload over a separate confidential channel; this is not client encryption directly to a GPU.
The SDK requires an attestation verifier supplied by the caller and verifies the encrypted reply and gateway receipt, with no plaintext fallback. The router still sees model, roles, message counts and sizes, timing, usage and authorization metadata. Ordinary chat reads request text in router memory on every lane. This adapter supports the attested lane and Tor with blind tokens on the unlinkable lane; it does not make every router endpoint encrypted or carry sidecar trellis-hpke/v1 through the router. Read the encrypted-chat checks and limits.
Create capped keys and restrict access.
Create and update keys with include_byok_in_limit; responses echo the stored boolean. usage remains the router’s billed USD total. byok_usage is zero: provider-side BYOK expenditure is not measured here, and router charges appear only in usage. The selection does not change billing or budgets. DELETE adds a top-level deleted: true and keeps the data envelope; it disables the key and retains its records.
List keys with offset and limit (1–1000). An offset without a limit uses pages of 100; no pagination parameters preserves the full list. Disabled keys remain included; past the end the data array is empty. Order is newest first, with key hash breaking ties. Pages reflect current rows rather than a frozen snapshot.
USD floats keep their existing meaning and can round in JSON. usage_pico_usd and usage_period_pico_usd are exact integer strings (one USD = 10¹² pico-USD). usage_micro_usd is an integer string rounded up from the total to micro-USD (one USD = 10⁶ micro-USD); it is not an exact sub-micro amount. BYOK integer fields are zero. Read usage after disabling a key with its management credential. Disabling does not drain accepted calls; usage is a current counter, not a final settlement certificate.
Inference-only key provisioning is switched on at trellis.example; self-hosted routers enable it with INFERENCE_KEYS_ENABLED (default false). Where enabled, a management key may create a child with scope: "inference", or PATCH /api/v1/keys/defaults with that scope to make newly minted children default to it. GET that endpoint reads the account default. Existing keys retain access. A management key can explicitly create with scope: "account", including a successor management key; scope is fixed at creation. Inference-only keys cannot have management rights.
An inference-only key may call chat/completions, completions, embeddings, responses and messages, list models, read its own generations and receipts, and call the paid GET data tools under /api/v1/data where a router switches them on (DATA_TOOLS_ENABLED, default false). Saved account routes, presets and characters cannot be selected through a model name. Other routes return 403, including key administration, balances, teams, agents and account feeds. Stored restrictions stay active even when provisioning is switched off. Calls remain linked to the operator account and the router reads ordinary request text in memory. Public receipts remain accessible by identifier without a key; the scope limits authenticated access and does not make those receipts confidential.
Review unused keys
Open API keys in the Keys & limits tab to see when each key was last used. Review enabled keys unused for at least 30 days, select the ones you no longer need, and confirm once to switch them off. A key that has never been used appears after 30 days from creation. This browser's key is excluded. Management keys follow the same rules as other visible keys.
The list uses GET /api/v1/keys fields last_used, created_at and disabled; the current key comes from GET /api/v1/key. Last used records a charged call, not account browsing or failed or free calls. DELETE /api/v1/keys/:hash switches off each selected key without deleting its history. A bearer management key or team owner/admin key is required to switch keys off; team keys stay within the caller's existing access. Team keys keep their normal audit entries. Account keys do not currently create key-disable entries in Activity. Each change is separate; any failures are shown so you can review them.
Signing-key transparency log
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Every key a client encrypts to or verifies against is written to an append-only log (C2SP tlog-tiles, RFC 6962 hashing): receipt signing keys (receipt_key), Oblivious HTTP key configurations (ohttp_key_config), blind-token issuer keys (blind_issuer_key), measurement bundles (measurement_bundle), sidecar key bindings (attestation_binding), the data inventory (data_inventory) and the signed host policy (host_policy). Checkpoints are signed notes that independent witnesses cosign. GET /api/v1/tlog names the entry kinds and the witnesses; /api/v1/tlog/proof?kind=&sha256= returns an inclusion proof for one key, /api/v1/tlog/consistency a consistency proof between two checkpoints, and /tlog/checkpoint and /tlog/tile/… serve the raw log. Pin the log’s verifier key and the witness keys from a source other than the log.
The client check is opt-in: @trellis/client exports TransparencyLog, which refuses a receipt key, gateway key or issuer key that has no inclusion proof and throws SplitViewDetected, carrying both signed notes, when two checkpoints it saw cannot be reconciled by a consistency proof. Anyone can run a witness with scripts/tlog-witness.ts.
As an alternative to witnesses, the router can anchor each new checkpoint in the public Sigstore Rekor log (TLOG_REKOR_ENABLED): GET /api/v1/tlog/rekor lists every anchored checkpoint with its Rekor entry and inclusion proof, /api/v1/tlog/rekor/key publishes the anchoring key, and /api/v1/tlog/rekor/{size} returns the anchor for one checkpoint size. Compare the entries that key has at search.sigstore.dev with the router’s list: an entry the list does not explain, or two anchored checkpoints of one size with different roots, is evidence of a split view. The log is off by default on a self-hosted router (TLOG_ENABLED) and GET /api/v1/tlog answers 404 until it is on.
What we keep
The What we keep page is generated from the router’s data inventory: every category of data the router stores, with its purpose, retention and who can read it. GET /keep/inventory.json serves the same inventory as canonical JSON (keys sorted, no whitespace), and the page shows its SHA-256; curl -s https://<this site>/keep/inventory.json | sha256sum reproduces it.
With TLOG_DATA_INVENTORY on, the router appends that hash to its transparency log as a data_inventory entry when it starts, so a changed inventory leaves a dated record. GET /api/v1/tlog/proof?kind=data_inventory&sha256=<hash> returns the entry and its inclusion proof; the page runs that lookup in the browser and says when the log does not hold the hash.
Errors: try a similar model
When a model’s providers are unavailable, Chat can offer up to three available models with the abilities your message needs. Choose one to switch the Chat model and resend the same message. Trellis never switches for you. Suggestions cost nothing; the retry is a new call at the chosen model’s rates.
Availability errors from chat completions, Messages and Responses can include a top-level suggested_models array, ranked by closest estimated request cost. Each item has id, name, prompt_price and completion_price in dollars per token, and why. An empty array means no matching model is available. The original error status, code and message stay the same. Client errors, policy denials, rate limits and proven-only route refusals do not receive suggestions. Availability can change before a retry. Ordinary requests remain readable in router memory on every lane.
Check JSON before using it.
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Switched on at trellis.example. Self-hosted routers can enable STRUCTURED_OUTPUT_CHECK_ENABLED (default false). Each chat request must also choose trellis.json_check. Without both switches, the response and billing stay unchanged. Models must still support response_format; this option does not change routing requirements.
{
"model": "qwen/qwen3-32b",
"messages": [
{
"role": "user",
"content": "Return a JSON object with a \"summary\" field."
}
],
"response_format": {
"type": "json_object"
},
"trellis": {
"json_check": "validate"
}
}Choose validate to parse the final message without another provider call. With json_object, it must parse as an object. With json_schema, the router also checks response_format.json_schema.schema. The answer, usage and original signed receipt remain intact; the response adds X-Trellis-Json-Check: valid or invalid and receipt.structured_output with mode, valid and errors (JSON Pointer path and plain reason; the empty path means the root).
Choose repair to allow one correction call when the first answer is invalid. The same routed model and provider receive the original conversation, answer, schema and errors, with a request for corrected JSON only. Both calls are charged at their normal rates and pass the same account and agent rules. Repair requires a bearer API key; a blind token or per-call payment cannot authorize two charges. A single-use agent approval is not reused. Non-streaming repair bypasses the response cache. If authorization, credit or the provider prevents the correction, the first output is returned with valid: false and retry_error; its charge still applies. If the core settles a correction before refusing its attestation, that correction’s signed receipt and charge are included too; the refused answer is not returned.
receipt.structured_output.calls lists each served call with attempt, an exact USDC cost string and its complete signed receipt. total_cost is the sum of those charges; retry_attempted says whether a correction was requested, and initial_errors preserves the first failure after a served correction. Top-level usage and receipt identify the returned call only. A second charge is additional to the first, even if the correction is still invalid. There is never a second correction call.
For streams, the header is pending because it is sent before the answer finishes. The final receipt event carries the completed validation result. A streaming request choosing repair gets pending; repair-unsupported and repair_supported: false: it validates once, without an extra call. Content chunks and their hash-chain comments remain unchanged. An interrupted stream is invalid; a disconnect may prevent delivery of the final receipt.
The schema subset covers objects, arrays, strings, numbers, integers, booleans and null; properties, required fields, additional properties, items, enum, const, anyOf, nullable and type arrays; string length, number bounds, array length and property-count bounds; and local #/ references through $defs or definitions. Unknown assertions, including pattern and format, are refused before a provider call. Schemas are bounded to 4,096 nodes and 64 levels; answer checks to 1 MiB, 100,000 validation steps and 64 levels. Oversized or non-text answers are invalid and cannot be repaired. Only a single chat answer is supported (n: 1); council and dual verification cannot be combined with this option.
Presets can store trellis: { json_check: "validate" } or repair with their response format. Explicit request settings win. The feature flag still applies.
Validation checks syntax and this schema subset, not factual accuracy. It cannot guarantee a usable answer; callers must inspect valid. The supplemental validation report is unsigned and absent from receipt lookup. It is not written to generation receipts; existing batch-output retention can keep it with the answer. Each call’s payload, signature and v2 receipt remain independently verifiable. The router reads ordinary request and answer text in memory. This option does not hide prompts from Trellis.
Anthropic Messages API
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
POST /v1/messages (also at /api/v1/messages) is the Anthropic Messages API, for the Anthropic SDKs and Claude Code. The request is converted to a chat completion and sent through /api/v1/chat/completions inside the router, so the key, balance, limits, lane, signed receipt and response headers are those of a chat call. Authenticate with x-api-key or Authorization: Bearer. The model is a catalog id from GET /v1/models, or a name the operator mapped with ANTHROPIC_MODEL_MAP; an unmapped claude-* name is a 404 that says the router serves open models.
# Claude Code and the Anthropic SDKs: point them at the router.
export ANTHROPIC_BASE_URL=https://<router>
export ANTHROPIC_AUTH_TOKEN=$TRELLIS_API_KEY # or ANTHROPIC_API_KEY: the router reads x-api-key too
export ANTHROPIC_MODEL=qwen/qwen3-32b # a catalog id from GET /v1/models
export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen/qwen3-8b # the small model Claude Code uses for quick tasks
export ANTHROPIC_CUSTOM_HEADERS="X-Trellis-Lane: attested" # optional: refuse anything but a verified enclave
claudeText, image, tool_use and tool_result blocks, tools, tool_choice, stop_sequences, top_k and metadata.user_id are converted; max_tokens above the model’s output limit is lowered to it. The resulting cap is always sent to the provider, and the hold for a call is priced at the prompt bound plus that cap; a call is charged its actual usage and never more than its hold. Tools hosted by Anthropic, thinking and service_tier are accepted and not acted on, and named in the X-Trellis-Ignored header; PDF documents, mcp_servers and container are refused with a 400. POST /v1/messages/count_tokens counts without a call and without a charge. The count is the router’s prompt bound, the figure a hold is priced at: the UTF-8 bytes of the text and tool schemas plus fixed template allowances, and for an image the per-image token limit the model declares (input_token_limits in GET /v1/models). It is an upper bound, several times a tokenizer’s count for English text. An image sent to a model that declares no limit is refused with a 400 (unboundable_input), on a count and on a call.
POST /v1/messages
x-api-key: $TRELLIS_API_KEY
anthropic-version: 2023-06-01
{ "model": "qwen/qwen3-32b", "max_tokens": 256, "messages": [{ "role": "user", "content": "Hello" }] }
# Count tokens without a call (no charge):
POST /v1/messages/count_tokensThe reply’s id is the receipt id, repeated in the X-Receipt-Id and Inference-Id headers, and its trellis object carries the lane, the disclosure class, the provider, the cost and the signed receipt. X-Trellis-Lane: attested (or ANTHROPIC_CUSTOM_HEADERS in Claude Code) refuses anything but a verified enclave. Errors use Anthropic’s shape, with billing_error for an empty balance.
Ollama API
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
The Ollama API is served under /ollama for Ollama clients: Open WebUI, Continue, the ollama libraries and LangChain's ChatOllama. Set the client's host (OLLAMA_HOST) to https://<router>/ollama and send the key as Authorization: Bearer. Chat, generate and embed calls run on the same keys, lanes and signed receipts as chat completions; /api/tags, /api/show and /api/ps read the catalog, and /api/pull answers as if the model were already present.
# Any Ollama client: set its host to the router's /ollama path and send the key as a bearer token.
export OLLAMA_HOST=https://<router>/ollama
curl $OLLAMA_HOST/api/chat \
-H "Authorization: Bearer $TRELLIS_API_KEY" \
-H "X-Trellis-Lane: attested" \
-d '{ "model": "qwen/qwen3-32b", "messages": [{ "role": "user", "content": "Hello" }], "options": { "num_predict": 200 } }'Streams are application/x-ndjson: lines with done false, tool calls whole in one line, then a closing line with done true, done_reason, the counts and durations and a trellis object with the receipt id. Options map to the chat parameters where one exists (num_predict to max_tokens, repeat_penalty to repetition_penalty; with num_predict -1, -2 or absent the router still sends the provider an explicit cap, the model’s output limit); options that tune a local runtime are named in X-Trellis-Ignored. X-Trellis-Lane: attested works here as on every route.
Responses API
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
POST /v1/responses (also /api/v1/responses) is the OpenAI Responses API, for the OpenAI Agents SDK, the Codex CLI and other Responses clients. It is an adapter over the chat route: keys, per-call payment, blind tokens, limits, lanes (X-Trellis-Lane) and signed receipts are the chat route’s own, and the answer comes back in the Responses shape, as a JSON body or as the Responses event stream.
# OpenAI Agents SDK (Python)
from agents import set_default_openai_client
from openai import AsyncOpenAI
set_default_openai_client(AsyncOpenAI(base_url="https://<router>/api/v1", api_key=TRELLIS_API_KEY,
default_headers={"X-Trellis-Lane": "attested"}))
# Codex CLI (~/.codex/config.toml)
[model_providers.trellis]
name = "Trellis"
base_url = "https://<router>/api/v1"
env_key = "TRELLIS_API_KEY"
wire_api = "responses"The route is stateless: nothing is stored, so store must be false (the default; store: true is refused), and previous_response_id, conversation, background, stored prompts and file or item references are refused with a 400 that names the field. Send the whole conversation in input on every request, including function_call and function_call_output items for tool round trips. Function tools and custom (freeform) tools run; hosted tools are refused, because Trellis hosts none. A custom tool such as Codex's apply_patch is offered to the model as a function with one string argument, input; a call to it comes back as a custom_tool_call item, and a custom_tool_call_output item is its result on the next turn. The tool's description and its grammar, if it has one, become the function's description as guidance only: nothing checks or enforces it.
Batches
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
POST /api/v1/batches (also /v1/batches) takes many chat completion or embeddings requests in one call and runs them in the background on the router’s worker. A batch line costs what the same call costs: there is no batch discount by default (BATCH_DISCOUNT_BPS is 0, and a router refuses to start with a discount that no margin funds). It is the OpenAI Batch API shape without files: send the lines inline as requests or as input_jsonl, one request per line with a unique custom_id; input_file_id is refused, because there is no files endpoint. Needs a prepaid key. Every line’s prompt bound is checked before the batch is accepted: a line whose input cannot be bounded (an image for a model that declares no per-image token limit, a tool the provider runs itself) makes the whole batch a 400 that lists the line with code unboundable_input, and one that batches too many prompts with prompt_batch_too_large.
POST /api/v1/batches
Authorization: Bearer $TRELLIS_API_KEY
{
"endpoint": "/v1/chat/completions",
"requests": [
{ "custom_id": "q-1", "method": "POST", "url": "/v1/chat/completions",
"body": { "model": "qwen/qwen3-32b", "messages": [{ "role": "user", "content": "Summarise ..." }] } }
]
}GET /api/v1/batches lists batches, GET /api/v1/batches/{id} shows one, POST /api/v1/batches/{id}/cancel stops it, and /output and /errors return JSON Lines for 24 hours after the batch finishes (410 batch_results_expired afterwards). The request lines and answers are never written to the database: until the results expire they are kept sealed (AES-256-GCM) in Redis, or in the router's memory without Redis, and then deleted; the database keeps only counts, costs, statuses and generation ids. Each line is billed, limited by the key's budget and rate limits, routed by its lane and receipted as the call it is; a failed line is not charged, and lines not run within the 24-hour completion window expire unrun and are not charged.
Characters
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A character is a Tavern card (V2 or V3, as JSON or a PNG that carries one) called as the model @character/<id>. POST /api/v1/characters creates one as public, unlisted (the default) or private; a private card is encrypted on the client with sealCard from @trellis/client/characters, and the router keeps only the ciphertext and its hash. POST /api/v1/characters/{id}/chat is a chat completion with the card as the prompt; the lane defaults to attested when the model has an attested provider, and budgets, rulebooks and signed receipts apply as on any call. /greetings, /export, /usage and /characters/group/next (turn order in a group) complete the set.
SillyTavern
API: Chat Completion
Chat Completion Source: Custom (OpenAI-compatible)
Custom Endpoint: https://<router>/api/v1
Custom API Key: <your Trellis key>
Model ID: @character/<id>Memory (/api/v1/memory) is a ledger of summaries, facts, lorebook entries and state, encrypted on the client: the router stores ciphertext under a scope it cannot link to a character, and stores an embedding for search only with embedding_opt_in: true, because a vector derived from the text can leak its topic. Memory sent inline with a chat call is used for that call only and never stored. Creator attribution is counts and cost only.
Files and retrieval
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
POST /api/v1/rag answers a question from documents sent with it, keeping nothing. The router cuts the documents into overlapping chunks, embeds the chunks and the question through POST /api/v1/embeddings, ranks the chunks by cosine similarity in memory and answers from the best top_k through POST /api/v1/chat/completions, citing numbered sources. Every step is an ordinary call of your key: billed, limited, routed by lane and receipted, and the response lists every receipt id with its lane. POST /api/v1/rerank orders passages against a query on its own. Needs a prepaid key.
POST /api/v1/rag
Authorization: Bearer $TRELLIS_API_KEY
{ "model": "qwen/qwen3-32b", "question": "What does clause 4 require?",
"documents": [{ "id": "contract", "text": "..." }, "a second document as a plain string"], "top_k": 6 }The Ask page runs the same flow in the browser, reading PDFs locally before anything is sent.
MCP
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
POST /mcp is a remote Model Context Protocol server: one JSON-RPC 2.0 message per request (initialize, ping, tools/list, tools/call), replies as JSON, no sessions. Its tools are list_models, list_attested_models, chat, verify_provider, get_receipt and verify_receipt; only chat needs an API key, which it spends like a chat completion. chat takes lane (public or attested) and disclosure, and on the attested lane returns an error rather than a downgraded answer when no verified enclave can serve the model (nothing sent, nothing charged). With the paid tools market on, trellis_tools_search and trellis_tools_call are added.
{ "mcpServers": { "trellis": { "url": "https://<router>/mcp", "headers": { "Authorization": "Bearer <your Trellis key>" } } } }SDKs
Every SDK speaks the same router API and surfaces the signed receipt of each call. None is published to a package registry yet; each installs from the repository's sdks/ folder as its README shows.
| Package | Language | Covers |
|---|---|---|
@trellis/sdk | TypeScript (ESM and CJS) | chat, streaming with the chunk chain, embeddings, rerank, batches, presets, models with lanes, receipts v1 and v2 |
trellis | Python 3.10+ (sync and async) | the same surface; receipts verified with cryptography |
trellis-go | Go 1.22+ | chat, streaming, embeddings, rerank, batches, models, receipt verification |
@trellis/langchain, langchain-trellis | TypeScript, Python | ChatTrellis and TrellisEmbeddings; receipt in response_metadata |
llama-index-llms-trellis | Python | Trellis LLM; receipt_of(response) |
Each reads TRELLIS_BASE_URL and TRELLIS_API_KEY, sends the lane as X-Trellis-Lane and provider.lane (never loosening a stricter lane already in the request), and turns the router’s { error: { code, message, type } } into a typed error with Retry-After. The TypeScript SDK wraps @trellis/client, which holds the receipt, attestation, transparency-log and blind-token checks. The HTTP API is described in OpenAPI 3.1 at /openapi.json.
Why this route?
Built, not enabled at launch. Route explanations are a setting the core launch surface does not accept, so a router at launch adds no route header and no route object to a receipt.
Route explanations are switched on at trellis.example. ROUTE_EXPLAIN_ENABLED defaults to false. When an operator enables it, ordinary chat, text completions and embeddings include a compact JSON x-trellis-route header once the serving provider is known, and an optional route object in the signed receipt. Streams carry it in the header and the final receipt event. With explanations enabled, stream headers wait for the existing routing attempt to find the first meaningful output; no second selection or provider call is made. Chat shows “Why this route?” only when that receipt evidence is present.
The extension has its own v: 1; the enclosing canonical-JSON receipt remains v1 and the COSE receipt remains v2 where issued (embeddings use v1 only). Both signatures cover the entire optional claim. Older receipts omit it. With the flag off, no field or header is added and the existing signed bytes stay unchanged. Verifiers check the extension’s version, fixed vocabulary, counts and serving-provider identity; a valid signature establishes the router’s statement, not an independent replay of selection.
Fields are provider (the serving provider id), reason, eligible (candidate offers in this model’s final plan, after provider and parameter rules and fallback restrictions, before the attempt limit), skipped (counts grouped by a fixed reason), lane, parameters (required names from a fixed list), and network_host. A fallback adds error-class counts in fallback, including failures on earlier models. It names no failed or skipped provider. Unknown skip or error reasons become other.
Reasons distinguish price, latency or output-speed order, weighted choice, preferred performance, provider order, your own provider key, a single eligible provider, required parameter support and fallback. Weighted choice uses price, health, quality and hardware checks; eligible network hosts can also receive network weights. It does not always choose the cheapest or healthiest provider. Lane rules and disclosure checks still apply. Parameter names describe routing rules; where the existing selector accepts undeclared support, this summary does not establish support. Dual-verification receipts describe each partition; council receipts describe each member or judge’s provider call. A top-level explanation does not describe the whole panel.
Cache replies and encrypted-chat receipts have no new selection explanation. Provider ids outside the safe header vocabulary omit the extension. No prompts, answers, other callers’ records, provider URLs, keys, raw error messages or numeric weights are added. The summary is retained in the existing generation receipt fields under their current retention rules. Ordinary request text remains readable by the router in memory; this feature makes no new prompt-privacy claim.
Sign account webhooks
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
WEBHOOK_SIGNING_ENABLED defaults to false. Signed webhooks are switched on at trellis.example. When enabled, Webhooks in your account manages destinations, events, rotation, revocation and the last 100 delivery attempts. An account management key adds destinations. Owner/admin keys outside agent sessions can manage linked destinations scoped to their own key. The disabled flag preserves existing alert behaviour.
New destinations receive a random secret shown once on creation; rotation reveals a replacement once. The router stores it encrypted under APP_SECRET and reads it in memory to sign notices. Existing destinations remain unsigned until rotated. Revocation removes the credential and stops future delivery; a request already in flight can finish. Keep the receiver’s secret outside source code. URLs use guarded HTTPS egress with public DNS answers pinned and redirects refused.
Each enabled delivery carries x-trellis-event-id. Signed deliveries also carry x-trellis-signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 using the literal secret string over timestamp, a period and the exact body bytes. Signed bodies include event_id matching the header. Verify before parsing or processing, reject timestamps more than five minutes in either direction, compare in constant time, and atomically reject duplicate event IDs. Retries keep the event ID and receive a fresh timestamp/signature.
Subscribe to spending and agent alerts, approval requests and decisions, credited deposits, funded/disputed/ruled agreements, observed status changes of hosts your account operates, and issued make-good refunds (refund.issued, queued with the refund when MAKEGOOD_ENABLED is on; reference: the refund id, status: the rule). New notices contain only id, type, source reference, time and fixed status; linked spending and agent alerts retain their existing fields with event_id added when signed. Approval references name the approval record. No prompt or answer text is included. Event availability follows the source feature flags.
The minute worker reads 50 destinations per tick, one activity page per destination, and sends at most 100 notices per tick. Creation sets the lower time bound; durable pagination and five minutes of overlap catch ordinary late commits. Source deletion before discovery or commits delayed beyond that overlap can lose notices. Approval requests/decisions and operated host status changes are queued when the router records them, in the same transaction. Changes between worker ticks are retained. Direct database writes outside those router writers do not create notices. Three delivery attempts are separated by five minutes. Delivery metadata stays for 90 days, with no bodies stored. A stopped worker delays delivery. A crash after sending can repeat a notice.
Use GET/POST /api/v1/webhooks, PATCH/DELETE /api/v1/webhooks/{id}, POST /rotate or /revoke, GET /deliveries and POST /test under that destination path. The endpoint check is queued, limited to one per minute and sent even if no event subscription matches. Removing a linked destination requires removing its URL in Spend Watch; revocation can stop it here.
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody is a Buffer of the original HTTP body, before JSON parsing.
function verify(secret: string, rawBody: Buffer, signature: string,
eventId: string, now = Math.floor(Date.now() / 1000)) {
const m = /^t=(\d{1,12}),v1=([a-f0-9]{64})$/.exec(signature);
if (!m || Math.abs(now - Number(m[1])) > 300) return false;
const expected = createHmac('sha256', secret)
.update(m[1] + '.').update(rawBody).digest();
if (!timingSafeEqual(expected, Buffer.from(m[2], 'hex'))) return false;
try { return JSON.parse(rawBody.toString('utf8')).event_id === eventId; }
catch { return false; }
}
// Read x-trellis-signature and x-trellis-event-id; verify first.
// Then atomically claim eventId in durable storage before side effects.
// A repeated ID returns success without repeating the side effects.
// Keep processed IDs for at least 90 days; use an outbox for effects.import hashlib, hmac, json, re, time
def verify(secret, raw_body, signature, event_id, now=None):
# raw_body: exact received bytes, before decoding or JSON parsing.
now = int(time.time()) if now is None else now
m = re.fullmatch(r"t=(\d{1,12}),v1=([a-f0-9]{64})", signature)
if not m or abs(now - int(m[1])) > 300:
return False
expected = hmac.new(secret.encode(), m[1].encode() + b"." + raw_body,
hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, m[2]):
return False
try:
return json.loads(raw_body)["event_id"] == event_id
except (ValueError, KeyError, TypeError):
return False
# After verification, atomically claim event_id in durable storage.
# Keep processed IDs for at least 90 days, and use an outbox for effects.
# Return success for repeated IDs without repeating their effects.Tracing
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A key can send spans of its public-lane calls to your own observability backend: PATCH /api/v1/keys/{hash} with a tracing object of type otlp (any OpenTelemetry collector over OTLP/HTTP JSON), langfuse or helicone. Spans follow the OpenTelemetry GenAI semantic conventions and add trellis.cost_usd, trellis.receipt_id, trellis.lane and trellis.provider. Prompt and completion text is included only with include_content: true. Attested and unlinkable lane calls are never exported. The API keys tab in your account edits the same setting and shows the export count, failures and whether delivery is paused after repeated failures; the secret is write-only and never returned.
PATCH /api/v1/keys/<hash>
{ "tracing": { "type": "otlp", "endpoint": "https://api.honeycomb.io/v1/traces",
"headers": { "x-honeycomb-team": "<Honeycomb key>" }, "include_content": false, "enabled": true } }- Honeycomb (OTLP): endpoint
https://api.honeycomb.io/v1/traces, headerx-honeycomb-team. - Grafana Cloud Tempo (OTLP): the stack's OTLP endpoint with its basic-auth
Authorizationheader. - Langfuse: type
langfuse, the host and the project's public and secret keys. - Helicone: type
heliconeand the Helicone API key; spans arrive as Helicone requests.
Teams
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A team is a pseudonymous organisation: an owner, members who join by passkey or wallet, roles (owner, admin, dev, viewer, agent), an organisation budget and a hash-chained audit log. POST /api/v1/teams creates one; /invites issues an invitation for a role, /join/challenge and /join let a member accept it, /sign-in/challenge and /sign-in mint a key for a member, and /members/{hash} and /principals/{pid} change or remove roles.
Owner binding: POST /api/v1/teams/{id}/owner/challenge returns a one-time message for the wallet to sign, and POST /api/v1/teams/{id}/owner takes the base58 Solana address and the wallet's ed25519 signature over that message, which the router verifies against the address. The bound wallet then signs in as owner. A multisig vault cannot sign a message, so it is not bindable yet; the page labels an owner as wallet or multisig accordingly.
The audit log (GET /api/v1/teams/{id}/audit) records every change with the previous entry's hash; /audit/roots publishes hourly roots and /audit/export returns the log as JSON Lines or CSV. Verify an export offline with node scripts/verify-audit.mjs <file>, which recomputes the chain and compares it with the roots.
Pay x402 tools from your balance
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet. A paid call also needs the operator's buyer wallet, TOOLS_BUYER_PRIVATE_KEY, a dedicated key holding USDC; /api/v1/status reports tools.ready only when both are set.
POST /api/v1/tools/call takes resource (an https address, with its query arguments), method (GET or POST), an optional JSON body of up to 64 KiB and max_price in USD. The router asks the tool unpaid and reads its 402 in either x402 version: a v1 JSON body with accepts or a v2 PAYMENT-REQUIRED header. It pays only scheme exact in USDC (mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) on Solana mainnet; a tool that asks for another asset, network or scheme is refused. A quote above max_price (the tool price; the router adds no markup, TOOLS_TAKE_BPS defaults to 0), above the router's per-call ceiling or outside your rulebook is refused before anything is held or paid.
Otherwise it holds the price plus the take on your key, signs a USDC transfer from its own wallet to the seller's payTo as an x402 exact payment on solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (the seller's facilitator settles it, fee sponsored), and retries with X-PAYMENT or PAYMENT-SIGNATURE. A 2xx JSON or plain-text answer of at most 2 MB is charged once and returned as untrusted data with a tool.call receipt: a COSE_Sign1 under the receipt key carrying the seller, the address without its query, the price, the answer's SHA-256 and the settlement transaction signature from the seller's payment response. POST /api/v1/receipts/verify checks it. Any other answer is refused and not charged; its hold is released once the signed transfer expires unused (its blockhash lapses). If the seller settles the transfer anyway, the call is charged, so the buyer wallet cannot be drained by failing on purpose.
Rulebooks gain a tool price dimension: tools.allow and tools.deny match a paid tool by exact address, address prefix ending in *, host, *.host, seller wallet or listing id; tools.max_price_per_call and tools.daily_budget are in USD; spending caps and approvals cover tool spend too. A tool's answer reaches a model only when tools.pass_to_models is true and the call adds then: { model, prompt }; the answer is then wrapped as data the model is told not to obey.
curl -s https://trellis.example/api/v1/tools/call \
-H "Authorization: Bearer $TRELLIS_API_KEY" \
-H "content-type: application/json" \
-d '{"resource":"https://tool.example/quote?symbol=NVDA","max_price":0.02}'
# data.response holds the tool's answer (untrusted), data.receipt the signed tool.call receipt.{
"version": 1, "models": {}, "caps": { "per_day_usd": 5 }, "on_breach": "deny",
"tools": {
"allow": ["https://tool.example/*", "*.data.example"],
"max_price_per_call": 0.05,
"daily_budget": 1,
"pass_to_models": false
}
}Sellers list a tool with POST /api/v1/tools/listings and a known-answer canary. The router checks the address answers 402 with a payable offer and records its payTo; later calls are refused if the payTo changes. Each listed tool gets a paid probe every day; three failures in a row delist it, and the state shows on the tool catalog and GET /api/v1/tools. A Skills Hub skill's paid invocation is a listing that names the skill; installing works as before. Sellers who list through the Trellis facilitator appear in search without a canary. With TOOLS_PUBLIC_CATALOG_URL set, search also covers that public catalog.
POST /api/v1/tools/listings
{ "name": "Quotes", "summary": "Delayed stock quotes.",
"resource": "https://tool.example/quote", "method": "GET",
"canary": { "query": "symbol=NVDA", "expect": { "contains": "\"symbol\":\"NVDA\"" } } }Over MCP, trellis_tools_search finds tools and trellis_tools_call pays one with the connection's key, under the same rulebook. Egress uses the provider egress guard: public https destinations only, DNS pinned, no redirects. The router's buyer wallet authorizes at most TOOLS_DAILY_LIMIT_USD per day across all keys.
Agent rulebook
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Attach a rulebook with PUT /api/v1/agents/:key_hash/policy. It controls allowed models, lanes, declared tools, UTC windows, output tokens and estimated request cost, with rolling hour, day and week caps from charged usage plus open reservations. A session key and its parent must both pass. Only account management keys and team owners or admins can manage rulebooks.
GET /api/v1/agents lists keys; /agents/me describes the calling key and inherited caps. POST /agents/check evaluates an Intent without recording it. POST /agents/:key_hash/kill stops the agent: it refuses the next request across router replicas; /resume clears the stop. GET /agents/:key_hash/events returns a hash chain of metadata decisions. A breach can deny the request or stop the agent; costs above an approval threshold return agent_approval_required.
AGENT_POLICY_ENABLED defaults to false, with these routes returning 404. Enforcement is deterministic code in Trellis’s router for requests through Trellis only. The router reads request text in memory on ordinary inference paths. These rules have no on-chain enforcement. Decision events contain model, lane, cost, token and tool identifiers, with 90-day retention when the cleanup worker runs.
Switched on at trellis.example.
Read and respect rules from MCP or an SDK
The SDK code is in the repository; npm and PyPI releases are not published yet.
Check before expensive calls and never retry a denied call unchanged. Connect MCP at POST /mcp with the calling key in the Authorization header. trellis_agent_rules returns that key’s rules, inherited rules, remaining rolling caps and stop state. trellis_agent_check returns the REST decision and reasons unchanged; token estimates use the current model catalog. Supply est_cost_pico instead to provide an explicit cost estimate.
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"trellis_agent_rules","arguments":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
"name":"trellis_agent_check","arguments":{
"model":"author/model","lane":"public",
"est_input_tokens":100,"max_output_tokens":32,"tools":[]}}}Both SDKs return the data object from /agents/me and /agents/check. Costs use decimal strings in pico USD: 10^12 pico equals one USD. A dry run reserves no budget, sends no prompt and creates no policy event; a later request is evaluated again and may be refused. Rulebook reads and dry runs remain available when the key is stopped or its tool allowlist excludes these inspection tools.
import { Trellis, AgentPolicyDenied, AgentKilled,
AgentApprovalRequired } from "@trellis/client";
const client = new Trellis({ baseUrl: routerUrl, apiKey });
const rules = await client.agent.rules(); // inherited rules and remaining USD caps
const decision = await client.agent.check({
kind: "inference", model: modelId, lane: "public",
est_cost_pico: "1000000000", max_output_tokens: 32, tools: [],
});
if (decision.decision === "allow") {
try {
await client.chat.completions.create({
model: modelId, messages: [{ role: "user", content: "Hello" }], max_tokens: 32,
});
} catch (error) {
if (error instanceof AgentPolicyDenied || error instanceof AgentKilled ||
error instanceof AgentApprovalRequired) {
console.error(error.message, error.reasons);
// Never retry the denied call unchanged.
// Approval refusals expose approval_id and poll when the router supplies them.
} else { throw error; }
}
} else { console.error(decision.reasons); }from trellis_client import (Trellis, AgentPolicyDenied,
AgentKilled, AgentApprovalRequired)
with Trellis(router_url, api_key) as client:
rules = client.agent.rules()
decision = client.agent.check({
"kind": "inference", "model": model_id, "lane": "public",
"est_cost_pico": "1000000000", "max_output_tokens": 32, "tools": [],
})
if decision["decision"] == "allow":
try:
client.chat({"model": model_id, "messages": [
{"role": "user", "content": "Hello"}], "max_tokens": 32})
except (AgentPolicyDenied, AgentKilled, AgentApprovalRequired) as error:
print(str(error), error.reasons)
# Never retry the denied call unchanged.
else:
print(decision["reasons"])AgentPolicyDenied, AgentKilled and AgentApprovalRequired preserve the router’s message, reasons, status, policy_sha256 and metadata in details. Approval refusals expose approval_id and poll only when supplied; these SDK methods do not create approvals or poll automatically. AGENT_POLICY_ENABLED must be enabled by the operator; it defaults to false. These interfaces do not change who reads inference text: Trellis’s router reads ordinary chat text in memory; the encrypted-chat adapter forwards ciphertext.
Switched on at trellis.example.
Read and respect rules from MCP or an SDK
The SDK code is in the repository; npm and PyPI releases are not published yet.
Check before expensive calls and never retry a denied call unchanged. Connect MCP at POST /mcp with the calling key in the Authorization header. trellis_agent_rules returns that key’s rules, inherited rules, remaining rolling caps and stop state. trellis_agent_check returns the REST decision and reasons unchanged; token estimates use the current model catalog. Supply est_cost_pico instead to provide an explicit cost estimate.
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"trellis_agent_rules","arguments":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
"name":"trellis_agent_check","arguments":{
"model":"author/model","lane":"public",
"est_input_tokens":100,"max_output_tokens":32,"tools":[]}}}Both SDKs return the data object from /agents/me and /agents/check. Costs use decimal strings in pico USD: 10^12 pico equals one USD. A dry run reserves no budget, sends no prompt and creates no policy event; a later request is evaluated again and may be refused. Rulebook reads and dry runs remain available when the key is stopped or its tool allowlist excludes these inspection tools.
import { Trellis, AgentPolicyDenied, AgentKilled,
AgentApprovalRequired } from "@trellis/client";
const client = new Trellis({ baseUrl: routerUrl, apiKey });
const rules = await client.agent.rules(); // inherited rules and remaining USD caps
const decision = await client.agent.check({
kind: "inference", model: modelId, lane: "public",
est_cost_pico: "1000000000", max_output_tokens: 32, tools: [],
});
if (decision.decision === "allow") {
try {
await client.chat.completions.create({
model: modelId, messages: [{ role: "user", content: "Hello" }], max_tokens: 32,
});
} catch (error) {
if (error instanceof AgentPolicyDenied || error instanceof AgentKilled ||
error instanceof AgentApprovalRequired) {
console.error(error.message, error.reasons);
// Never retry the denied call unchanged.
// Approval refusals expose approval_id and poll when the router supplies them.
} else { throw error; }
}
} else { console.error(decision.reasons); }from trellis_client import (Trellis, AgentPolicyDenied,
AgentKilled, AgentApprovalRequired)
with Trellis(router_url, api_key) as client:
rules = client.agent.rules()
decision = client.agent.check({
"kind": "inference", "model": model_id, "lane": "public",
"est_cost_pico": "1000000000", "max_output_tokens": 32, "tools": [],
})
if decision["decision"] == "allow":
try:
client.chat({"model": model_id, "messages": [
{"role": "user", "content": "Hello"}], "max_tokens": 32})
except (AgentPolicyDenied, AgentKilled, AgentApprovalRequired) as error:
print(str(error), error.reasons)
# Never retry the denied call unchanged.
else:
print(decision["reasons"])AgentPolicyDenied, AgentKilled and AgentApprovalRequired preserve the router’s message, reasons, status, policy_sha256 and metadata in details. Approval refusals expose approval_id and poll only when supplied; these SDK methods do not create approvals or poll automatically. AGENT_POLICY_ENABLED must be enabled by the operator; it defaults to false. These interfaces do not change who reads inference text: Trellis’s router reads ordinary chat text in memory; the encrypted-chat adapter forwards ciphertext.
Switched on at trellis.example.
Spending limits
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
One editor sets spending limits wherever a key’s spending is controlled: Spending limits in the chat Tools panel, each agent on /agents, and Spending limits on any key in the dashboard’s API keys. The fields, words and order are the same in each place, and saving writes that key’s rulebook with PUT /api/v1/agents/:key_hash/policy. Spending limits cover requests through Trellis only; they do not control calls sent elsewhere.
- Cap per request, hour, day and week ($): caps.per_request_usd, per_hour_usd, per_day_usd and per_week_usd. Per request is compared with the amount the router holds for the request, which is a bound and not an estimate: the prompt at its UTF-8 bytes plus the output cap (max_tokens, or the model’s output limit when none is sent). It is more than the usual final charge, so set the cap against the hold; a lower max_tokens lowers it. Hour, day and week are rolling windows that include requests still running. A blank cap adds no cap.
- Ask me first above ($): approval.above_usd. Above it, the router refuses with agent_approval_required until you approve on /agents or inline in chat; the approved request is then retried. Each approval is single use and expires.
- Stop and Resume: POST /api/v1/agents/:key_hash/kill and /resume. Stop refuses the next request through Trellis until you resume. A request already running may finish and is still billed. They act on saved limits, so save limits first.
- Models, lanes and tools, on /agents and in the dashboard: the rulebook’s models, lanes and tools allow and deny lists. Deny wins.
Chat uses a dedicated chat key. POST /api/v1/sessions creates it with a total (budget_usd, up to $1,000) and an expiry (ttl_minutes, 1 to 1,440), then its rulebook carries the caps and the ask-first amount. The total and expiry stay fixed for that chat key; caps and the ask-first amount can change. Remove spending limits revokes the chat key. It stays in that tab’s session storage, and anyone with access to the tab can use it.
On /agents the editor also holds the rulebook’s other rules: maximum output tokens, asking first after a number of calls per rolling hour, what happens when a limit is reached, UTC windows, circuit breakers and alerts. The dashboard and chat editors keep those rules as they are when they save.
In the dashboard’s API keys, the editor also sets the key’s total budget, beside the caps. That is the key’s own limit, saved with PATCH /api/v1/keys/:hash, and it applies alongside the rulebook. Blank means no total budget. When only the total budget changes, saving leaves the rulebook as it is. Under it, Auto top-up can raise the total budget from your account credits when it runs low, within a weekly maximum, saved with the same PATCH.
Where Agent Guard is switched on, the editor adds an Actions section for the rulebook’s actions: cap per action, cap per day, actions per hour, ask me first above, and allowed or denied actions and targets. Rules apply to actions your agent checks first. Wired into your code before the order function, the model can't skip the check; it doesn't stop whoever holds the brokerage or wallet keys. Amounts traded count what your agent reports.
Only account management keys and team owners or admins can change spending limits. A session key cannot change its own.
Default route
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A key owner can set a default route once, in the key’s rulebook: route_default in PUT /api/v1/agents/:key_hash/policy, or Default route in Spending limits, next to the lanes, on the Agents page or for a key under API keys. It applies only to a request that names no lane. A lane named by provider.lane, provider.disclosure, provider.lane_downgrade, provider.private, a :private model, the X-Trellis-Lane, X-Trellis-Disclosure-Max or X-Trellis-Lane-Downgrade header, the key’s routing settings, a saved route, a preset or a character always wins.
- Standard provider (
standard, the default): served as today, on the public lane. - Proven hardware only (
proven_only): served exactly as laneattested, only by endpoints with a fresh hardware attestation the router verified. When none can serve it, the request gets the same 503no_attested_endpointrefusal and nothing is charged. - Proven hardware first (
proven_first): laneattestedwhen the model has an attested endpoint that would take the request at that moment, otherwise an ordinary public request. The check runs once, before routing. A request served on the public lane is receipted and labelled as the standard route, never as proven hardware; once laneattestedis chosen, its rules apply in full, refusal included.
The rulebook’s lanes allowlist still applies and the stricter rule wins: Proven hardware first never picks attested when the allowlist leaves it out, and Proven hardware only under an allowlist without attested is refused with lane_not_allowed. A session key also follows its parent’s rulebook; where both set a default, the stricter one applies. A response a default applied to carries X-Trellis-Default-Route, for example proven_first; lane=public; the signed receipt records the lane that served it.
It covers chat and text completions (with the compatible, character and batch routes that run through them), embeddings, rerank and document questions (POST /api/v1/rag). For a document question, Proven hardware only makes the whole request one that asks for lane attested: the embedding model is picked among attested ones, and the request is refused before anything is sent when none qualifies, so no chunk reaches a standard provider. Proven hardware first is applied to each embeddings and answer call for its own model; the response’s lane stays public unless every call was held to attested, and each receipt shows the lane its call was served on. Encrypted chat is always served on proven hardware. There is no separate switch: the setting is read only while AGENT_POLICY_ENABLED is on, and that defaults to false. On every lane the router still reads ordinary request text in memory; proven hardware describes where the request is answered.
Starter setups
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A starter setup fills the spending limits editor with a set of values in one click. Choose Start from a setup at the top of Spending limits: for an agent on the Agents page, for a key under API keys in the dashboard, or in chat limits. Picking one lists what it sets and fills the fields; nothing is saved until you save, which writes that key’s rulebook with PUT /api/v1/agents/:key_hash/policy as before. Undo puts back the earlier values. Setups add no endpoint and no rulebook field: each is built from the starter rulebooks, Agent Guard’s action rulebooks and the default route, with their numbers unchanged. Spending limits cover requests through Trellis only; they do not control calls sent elsewhere.
- Careful chatbot, from Customer support bot. Small caps and short replies for a chatbot. Proven hardware when the model has it, otherwise a standard provider.
- Up to $0.01 a request and $0.2 in any hour and $1 in any 24 hours and $5 in any 7 days
- Asks you above $0.005 for a model or paid tool call
- No declared or paid tools allowed
- Only these lanes: standard, proven hardware
- Requests that name no lane: Proven hardware first
- Replies up to 256 tokens
- If a rule is broken: Refuse that request
- Stop at 5 requests in any minute; resume to run again; Stop at 3 denials in any 10 minutes; resume to run again
- No limit on models or hours
- Trading agent, from Trading agent: ask first after 60 calls an hour and Trading: market hours, $500 per order. The trading starter: ask first above an amount and after a number of calls an hour, on proven hardware when the model has it. Order rules and market hours where Agent Guard is on.
- Up to $0.25 a request and $1.5 in any hour and $3 in any 24 hours and $25 in any 7 days
- Asks you above $0.1 for a model or paid tool call
- Only these lanes: standard, proven hardware
- Requests that name no lane: Proven hardware first
- Only these actions: trade.order, trade.cancel; Only these action targets: STOCK_A, STOCK_B, STOCK_C, INDEX_FUND_A, INDEX_FUND_B; Actions up to $500 each; asks you above $250; Actions up to $2000 in any 24 hours; Up to 20 actions in any hour
- Replies up to 4096 tokens
- Asks you after 60 model calls in any hour
- If a rule is broken: Refuse that request
- Weekdays 13:30–20:00 UTC (start included, end excluded)
- Stop at 30 requests in any minute; resume to run again; Stop at 5 denials in any 10 minutes; resume to run again
- No limit on models or declared tools
- Batch jobs, from Trading agent: daily model budget. Higher caps for long runs on standard providers. The daily cap and a denials breaker stop a runaway loop.
- Up to $0.25 a request and $1.5 in any hour and $5 in any 24 hours and $25 in any 7 days
- Asks you above $0.1 for a model or paid tool call
- Only these lanes: standard, proven hardware
- Requests that name no lane: Standard provider
- Replies up to 4096 tokens
- If a rule is broken: Refuse that request
- Stop at 5 denials in any 10 minutes; resume to run again
- No limit on models or declared tools or hours
- Proven hardware by default, from Proven hardware only. Small caps. Every request goes to proven hardware, or is refused and not charged.
- Up to $0.02 a request and $0.1 in any hour and $0.5 in any 24 hours and $2 in any 7 days
- Asks you above $0.01 for a model or paid tool call
- No declared or paid tools allowed
- Only these lanes: proven hardware
- Requests that name no lane: Proven hardware only
- Replies up to 512 tokens
- If a rule is broken: Refuse that request
- Stop at 5 requests in any minute; resume to run again; Stop at 3 denials in any 10 minutes; resume to run again
- No limit on models or hours
Each editor fills only what it shows. Chat limits fill the caps and the ask-first amount, and offer Careful chatbot. API keys also fill models, lanes, the default route, tools and, where Agent Guard is switched on, actions. Agents also fills reply length, calls per hour, what happens over a limit, UTC hours and circuit breakers. Anything a setup does not list stays as it is, including the chat key’s total and expiry, autonomy, agreements and paid tool prices; alerts and actions change only when a setup carries them.
Trading agent’s order rules and market hours apply only where Agent Guard is switched on. UTC hours cover the whole rulebook, model calls included: 13:30–20:00 covers US market hours during daylight time; from Nov 1 use 14:30–21:00. On the Agents page, More starting points still lists each earlier starter rulebook and, where Agent Guard is switched on, each action rulebook; they now fill the editor the same way instead of saving at once.
With Proven hardware only, a request that names no lane goes only to endpoints with a fresh hardware attestation the router verified, and is refused with nothing charged when none can serve it. Proven hardware first falls back to a standard provider and labels the request as such. Proof-time shows how recently each attesting provider’s hardware was verified. On every lane the router still reads ordinary request text in memory.
Auto top-up
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A key’s total budget (its limit) stops an agent when it runs out, until someone raises it. Auto top-up keeps the agent going without handing it your whole account: “When this key has less than $X of budget left, add $Y from your account credits, at most $Z per week.” Set it in Spending limits on any key under API keys, in the Auto top-up row under the total budget, or with PATCH /api/v1/keys/:hash:
PATCH /api/v1/keys/:hash
{ "topup": { "below_usd": 2, "add_usd": 10, "max_per_week_usd": 50 } }- No money moves. The total budget is an allowance on your account’s own credits. A top-up only raises that allowance, and only while the account’s available credits (its balance less requests still running) cover the key’s whole remaining allowance after it.
- When it runs. After a charge leaves the key with less than
below_usd, and when the key’s budget would refuse a request while it has less thanbelow_usdleft, so a key stopped at its budget carries on once your account or the week allows. The router handles one account’s charges one at a time, so requests that cross the line together make one top-up. - The week.
max_per_week_usdcounts top-ups from Monday 00:00 to Sunday 24:00 UTC. Once it is reached, the key waits for the next week or for you to raise its budget. - Limits.
below_usdandadd_usdfrom $0.01 to $1,000,max_per_week_usdup to $5,000, andadd_usdno more thanmax_per_week_usd. The key needs a total budget that does not reset (nolimit_reset). In a team with an org budget, a top-up must still fit in it.topup: nullturns auto top-up off. - Every top-up is recorded. Each one shows in Activity under Top-ups and in your inbox, for example “Topped up Research agent by $10; $40 left this week”. When the router skips one, the inbox says why, once: not enough account credits, the weekly maximum, or the team budget. GET /api/v1/keys/:hash shows the rule and
topups_this_week_usd, the top-ups added since Monday.
Auto top-up is not a cap. The caps per request, hour, day and week in the key’s rulebook still apply to every request, before and after a top-up; a top-up raises the total budget only. Choose a below_usd at least as large as what the router holds for one request (its worst case: the prompt’s bytes plus the output cap, more than the usual final charge), so a request rarely waits for a top-up.
Replay your rules
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Before you save spending limits for a saved key or agent, Replay last 7 days runs the rules as they are in the editor against that key’s recorded calls and Agent Guard checks from the last 7 days, oldest first. It shows how many would have been allowed, sent to ask me first or refused, why, and up to 20 example calls beside what happened at the time. Replayed against your last 7 days. Nothing was saved. After you pick a starter setup, Replay it first does the same for that setup.
- POST /api/v1/agents/:key_hash/replay with the draft rulebook as policy and, optionally, days from 1 to 7. It needs the same permissions as saving that key’s rulebook, allows ten replays a minute per key, and reads in a read-only database transaction: nothing is saved, charged or changed.
- It reads up to 5,000 calls and actions, the key’s own and its session keys’: model, lane, cost, tokens and time, never the text. When there are more, truncated is true and a note says how far it reached.
- Running state is rebuilt the way the router keeps it: caps per hour, day and week (counting what was charged before the window), calls per hour, UTC windows, circuit breakers, progressive autonomy from its first step, and Stop. Once the rules stop the key, every later call is refused.
- What the record cannot tell is listed in notes rather than guessed: whether you would have approved a call sent to ask me first (it counts as not run), approvals given at the time, calls refused at the time (they have no recorded cost), and calls with no recorded estimate, output limit, tool list or lane.
The answer has window, evaluated, allowed, denied, asked, stopped_at when the rules would have stopped the key, by_reason, actual (what happened), changed, examples (time, model, lane, cost_usd, decision, reason and actual), truncated and notes. In the client libraries it is client.agent.replay(keyHash, policy).
Playbooks
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A playbook is one set of rules that many agents and API keys follow. Change it once, and every key that follows it uses the new rules on its next request. Make and change playbooks in the dashboard under Keys & limits, then Playbooks; choose which keys follow one from a key’s spending limits there or on /agents. A playbook starts from a starter setup, from a key’s current rules or from no rules, and is edited in the same spending limits editor.
- GET /api/v1/playbooks lists them, with how many keys follow each and which of those keys you manage. POST /api/v1/playbooks takes a name and a policy, the same rulebook body as PUT /api/v1/agents/:key_hash/policy; a management key can add team_id.
- GET /api/v1/playbooks/:id adds its recorded changes. PUT /api/v1/playbooks/:id takes a new name, new rules or both; new rules raise version by one and change sha256, the SHA-256 of the canonical rules.
- POST /api/v1/agents/:key_hash/playbook with playbook_id makes that key follow the playbook; playbook_id null stops following.
- DELETE /api/v1/playbooks/:id is refused with playbook_followed and the number of following keys while any follow it. With ?unlink=copy each of those keys keeps the rules as its own.
A following key’s rules are the playbook’s current version. A change is copied to every following key in the same transaction and under the same account lock as each request’s rule check, so every key uses it from its next request, exactly as when one key’s own rulebook is saved. Each following key’s event log records the change with the new sha256.
A key follows one playbook or keeps its own rules, never both: changing or removing a following key’s own rulebook is refused with playbook_linked. Stopping following keeps the playbook’s current rules as the key’s own, so nothing loosens. Following replaces the key’s own rules with the playbook’s. Stop and Resume, spend and progressive autonomy stay per key.
A team owner or admin makes and changes its team’s playbooks, which only that team’s keys can follow. Account-wide playbooks change only with a management key; team owners and admins can read them and have their keys follow them. Viewers, devs and agent keys cannot read or change playbooks. Every change is recorded with its version and sha256. For a team, it is also in the team’s audit log, and a change of rules appears in the inbox of the team’s owners and admins: “Playbook X changed; N keys follow it”.
Playbooks use the rulebook switch, AGENT_POLICY_ENABLED, which defaults to false; with it off, these routes return 404. Like every rulebook, a playbook covers requests through Trellis only.
Rulebooks in plain English
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Read your agent’s rules as short sentences before opening Edit. Starter setups, playbooks and approval prompts on Agents and in the inbox use the same words. Amounts keep every decimal place, so $0.005 stays $0.005. Model and paid tool budgets use rolling hours, days and weeks; working hours use UTC and exclude the end time. All rulebooks that apply to a key still apply, including inherited rules.
This changes how existing rules are shown. There is no new endpoint or policy field. GET /api/v1/agents and GET /api/v1/agents/:key_hash/policy return policies used by the page; GET /api/v1/playbooks returns playbook rules. These routes keep their existing Bearer-key account and team permissions. Approval decisions still use POST /api/v1/agents/approvals/:id/approve or /deny with an owner or admin key. A short approval line gives the amount cap and ask-first amount; it is not the full rulebook.
AGENT_RULEBOOK_WORDS_ENABLED defaults to false. It changes only Telegram approval wording in the existing linked delivery job, where Telegram linking and agent rulebooks must already be enabled. When enabled, Telegram receives readable approval details and the current amount-rule summary instead of a rules fingerprint. Inference messages and tool arguments are not included. The summary is current when read; it is not a saved copy of the rules at approval creation. The page needs no new flag. Rules constrain requests through Trellis and actions your agent checks first; ordinary request text remains readable by the router in memory.
Your agent asks you first
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
With AGENT_POLICY_ENABLED=true (default false), costs above a rulebook’s approval.above_usd, and model calls once the rolling hour already holds approval.above_calls_per_hour admitted calls (optional), return HTTP 403 agent_approval_required with metadata.approval_id, expires_at and poll. The router creates one pending approval for an identical intent and requesting key; a repeated request reuses it until expiry.
Switched on at trellis.example.
Approve on /agents, or in Telegram after an owner links it (switched on at trellis.example).
GET /api/v1/agents/approvals?status=pending lists up to 100 newest approvals visible to a management key or an owner/admin of the same account and team. The Agents page shows “Waiting for you” with Approve and Deny buttons. POST /api/v1/agents/approvals/:id/approve or /deny records that principal’s decision. GET /api/v1/agents/approvals/:id returns only id, status and expires_at to that principal or the requesting key. Session and ordinary agent keys cannot approve themselves.
After approval, retry with X-Agent-Approval: <id>. Approval is single-use, belongs to the requesting key, and binds the model, lane, declared tools and output token limit. The estimated cost here is the amount the router holds for the request, a bound and not an estimate (the prompt’s bytes plus the output cap); it may decrease but cannot exceed max_cost_pico. Council and dual requests bind every model and their combined estimate. Other caps, schedules and the stop switch are evaluated again. An approval is consumed with a successful reservation, even if the provider later fails; a cache hit can also consume it. Approval does not bind prompt contents; prompt text is excluded from the intent.
AGENT_APPROVAL_TTL_S defaults to 900 seconds, measured from the request, with bounds of 1–86400. Approval does not extend the deadline. Expiry ends validity; approval rows remain until operator deletion. Approval request, decision and use events enter the existing per-key hash chain, whose retention is 90 days when its worker runs. Approval metadata retains readable model and tool identifiers, estimated cost, token limit, principal key hash and timestamps. Trellis’s router reads ordinary chat text in memory on every lane; the encrypted-chat adapter forwards ciphertext.
TELEGRAM_LINKING_ENABLED defaults to false and requires AGENT_POLICY_ENABLED=true, plus TELEGRAM_BOT_TOKEN on the worker that runs the bot and alert jobs (the API only issues and checks link codes). Telegram linking and approvals are switched on at trellis.example. When enabled, Link Telegram on /agents or dashboard settings issues a single-use code valid for five minutes, with five issuance attempts per account per minute. Send /link <code> in a private chat with Trellis’s bot. No API key is sent to Telegram. Only management keys or account/team owner/admin keys may link; sessions cannot link. There is one Telegram identity per principal key, and one account per Telegram identity. Creating a new code invalidates the account’s previous code. Treat the code as an approval credential.
GET, POST and DELETE /api/v1/telegram/link read this principal’s status, issue a code and unlink or cancel its pending code. Off returns 404. Unlink also works with /unlink in the bot. Linked principals receive pending intent metadata with Approve/Deny buttons through the existing telegram-bot worker. Callbacks recheck the key, role, team scope, link generation and message, then run the dashboard’s approval decision logic. The message updates after a decision, including decisions made on the dashboard. No inference is executed by clicking a button; the agent must retry its bound request before expiry.
Telegram sees link codes, account-link commands, approval metadata and alert messages. Trellis stores the code’s hash, link account and principal key hash, Telegram user id, random link generation, timestamps and approval delivery markers, never Telegram message text or API keys for linking. Codes expire after five minutes; delivery markers expire with the approval and are removed on unlink. Expired metadata is purged on enabled polling or code issuance. The key is rechecked for every delivery and callback. A worker interruption can repeat a notification; decisions remain single-use. Chat keys connected through /key are separate and removed through /forget.
Allow this next time
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Next to Approve in Agents and your inbox, choose “Approve and allow next time” for an amount-based request. Review the exact ask-first amount change, then confirm. Only that agent’s ask-first amount rises, rounded up to the cent. Spending caps and other rules still apply. If the agent follows a playbook, open that playbook to change its rules there.
GET /api/v1/agents/approvals/:id/approve-and-allow previews field, before_usd, after_usd, amount_usd and policy_sha256. POST to the same path with a strict body containing policy_sha256 confirms that preview. Both require the same management or owner/admin key and account/team scope as Approve; inference and session keys are refused. AGENT_POLICY_ENABLED defaults to false; off returns 404. Actions also require AGENT_GUARD_ENABLED (default false). No additional flag or migration is needed.
The server approves the pending request and saves the rulebook’s new hash and schema version with a policy_set event in the same transaction. The approval keeps its single-use retry binding and original expiry. POST returns data.approval, data.change, data.policy, data.version and data.sha256. HTTP 409 refuses expired or decided approvals, non-amount reasons, changed rulebooks and playbook followers; playbook_linked includes playbook_id and playbook_name. A rulebook changed since the request needs a fresh approval. Telegram retains Approve and Deny; changing the threshold requires the web confirmation.
This changes the amount at which future requests ask first, including requests with different models or actions still permitted by the rulebook. Model calls use the estimated ceiling; Guard uses the agent’s reported amount. The router records the rulebook and approval changes in its existing tables and hash chain. It still reads ordinary request text in memory.
Ask before an action with money
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Agent Guard is switched on at trellis.example. Self-hosted routers enable it with AGENT_GUARD_ENABLED (default false), which requires AGENT_POLICY_ENABLED. While it is off, guard routes return 404 and its MCP tools are hidden. /api/v1/status reports agent_guard.enabled: true when it is on and omits the field when it is off; treat an absent field as unavailable.
Rules apply to actions your agent checks first. Wired into your code before the order function, the model can't skip the check; it doesn't stop whoever holds the brokerage or wallet keys. Amounts traded count what your agent reports.
- Model calls the MCP tool: a seatbelt. Ask trellis_guard_decide before acting; a model can omit a tool call.
- Code wraps the order function: the model can’t skip the check when every execution path goes through that wrapper. Use integrations/solana-agents/guard.ts or guard.py beside the decision-receipt helper.
- Guard controls execution: agent wallets with on-chain rules are the next step and are not part of this update.
Use the agent’s inference-only key to decide, report an outcome, read its rules and poll its approval. Keep the owner or management key outside the agent. POST /mcp internal calls still pass the same route scope checks; the agent cannot PUT policies, stop, resume or approve itself.
curl "$TRELLIS_URL/api/v1/guard/decide" -H "Authorization: Bearer $AGENT_KEY" -H 'Content-Type: application/json' -d '{"action":"payment.send","amount_usd":"40.00"}'POST /api/v1/guard/decide returns HTTP 200 with data.decision: allow, deny or approval_required. No rulebook or no actions section denies. Action names are owner-chosen; allow/deny lists match exactly or with a prefix ending in .*; denied entries win. Targets match exactly without case. An allowed target list requires a target. Amounts are decimal USD strings, up to 12 whole and 6 fractional digits; “0” is allowed for cancellations.
On approval_required, call trellis_guard_wait with approval_id (timeout_s 1–50, default 25), or poll GET /api/v1/agents/approvals/:id. Approve or deny on /agents or linked Telegram. On approved, call decide again with the same action, target and details_sha256 plus approval_id. The amount may decrease but cannot exceed the approved ceiling. Approval is single-use and expires after AGENT_APPROVAL_TTL_S (default 900 seconds). Limits, UTC windows and stop state are checked again. Never retry a denial unchanged. With on_breach: “kill”, a denied action stops subsequent requests until the owner resumes it on /agents, or sends /resume followed by the agent key hash in a private chat with linked Telegram.
Action per-request and rolling 24-hour amount limits are separate from model-spend caps. An unreported allow holds the requested amount; an executed outcome replaces it with the reported amount, while skipped or failed releases it. Every allow counts toward max_per_hour even if skipped. Trellis does not verify execution or the reported amount. Only the deciding key can report, once; repeats return 409. Outcomes above the requested amount are recorded with over_allowed: true; reporting does not retroactively undo an action.
curl "$TRELLIS_URL/api/v1/guard/decisions/$DECISION_ID/outcome" -H "Authorization: Bearer $AGENT_KEY" -H 'Content-Type: application/json' -d '{"status":"executed","amount_usd":"40.00"}'trellis_guard_report sends the same outcome. Executed requires amount_usd; skipped and failed may omit it. The helpers decide, wait, redeem approval, call your function on allow and report its outcome; a thrown function reports failed. Supply executedAmountUsd(result) in TypeScript or executed_amount_usd(result) in Python to report the actual amount. A report failure after execution must not cause the order function to be retried. Guard does not debit the action amount from your Trellis model balance.
Each decision includes data.signed with a payload of type trellis.guard.decision.v1, alg: Ed25519, key_id and sig. Verify the canonical JSON signature using the published receipt signing keys. The signature is the router’s statement, not independent proof of execution. A session inheriting multiple rulebooks uses a SHA-256 digest of their sorted policy hashes. Action decisions and outcomes join the existing hash chain. Decisions retain readable action names, target labels and reported amounts until operator deletion; full order details are excluded. Optional details_sha256 is the decision-receipt helper’s canonical JSON hash, connecting the order to the model call’s decision tag.
Suggested names: trade.order, trade.cancel, swap, token.approve, transfer.send, bridge.send, payment.send, invoice.pay, tool.buy, api.call, email.send, deploy.run. Windows are UTC and cover the whole rulebook, including model calls. The trading starter’s 13:30–20:00 covers US market hours during daylight time; from Nov 1 use 14:30–21:00. Its targets, STOCK_A, STOCK_B, STOCK_C, INDEX_FUND_A and INDEX_FUND_B, stand for the symbols your agent trades; list your own before you save it. These starters are configuration examples, not advice or a claim of affiliation with a brokerage; model spending and declared tools remain unrestricted until you add rules.
Trading: market hours, $500 per order
{
"version": 1,
"models": {},
"caps": {},
"windows": [
{
"days": [
1,
2,
3,
4,
5
],
"start": "13:30",
"end": "20:00"
}
],
"actions": {
"allow": [
"trade.order",
"trade.cancel"
],
"targets": {
"allow": [
"STOCK_A",
"STOCK_B",
"STOCK_C",
"INDEX_FUND_A",
"INDEX_FUND_B"
]
},
"per_action_usd": 500,
"per_day_usd": 2000,
"approval_above_usd": 250,
"max_per_hour": 20
},
"on_breach": "deny"
}On-chain: swaps yes, sending funds out never
{
"version": 1,
"models": {},
"caps": {},
"actions": {
"allow": [
"swap",
"token.approve"
],
"deny": [
"transfer.*",
"bridge.*"
],
"per_action_usd": 200,
"per_day_usd": 1000,
"approval_above_usd": 50,
"max_per_hour": 10
},
"on_breach": "kill"
}Payments: ask above $25
{
"version": 1,
"models": {},
"caps": {},
"actions": {
"allow": [
"payment.send",
"invoice.pay",
"tool.buy"
],
"per_action_usd": 100,
"per_day_usd": 500,
"approval_above_usd": 25,
"max_per_hour": 30
},
"on_breach": "deny"
}Pay another agent
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Paying another agent is switched on at trellis.example. Self-hosted routers turn it on with AGENT_PAY_ENABLED (default false), which requires AGENT_GUARD_ENABLED. While it is off, the pay routes return 404 with the message that it is not switched on, and /api/v1/status reports agent_pay.enabled: false.
Trellis does not hold the money. The paying agent’s own wallet sends USDC on Solana straight to the recipient’s wallet. Trellis does three things only: it decides with the payer’s rulebook through Agent Guard, it checks the transfer on chain afterwards, and it signs a receipt that links the decision to the transfer. No balance moves inside Trellis, there is no escrow, and nothing is sent through Trellis.
Recipient
An agent can add an optional payout_wallet (a 0x address) to its opt-in public profile, so others can pay it by profile id. Paying a raw 0x wallet works too. When exactly one live profile publishes that wallet, the payment is linked to that agent as well.
1. Ask the rulebook
curl "$TRELLIS_URL/api/v1/agents/pay" \
-H "Authorization: Bearer $AGENT_KEY" -H 'Content-Type: application/json' \
-d '{"to":"<profile id or Solana wallet>","amount_usd":"20.00"}'POST /api/v1/agents/pay takes the payer agent’s key and {to, amount_usd, memo_sha256?, approval_id?}. It runs the payer’s rulebook through Agent Guard as action pay.agent, with the target set to the recipient’s profile id or wallet, so the actions section’s allow and deny lists, targets, per_action_usd, per_day_usd, approval_above_usd and max_per_hour all apply. The answer is Agent Guard’s own: allow, deny or approval_required, with decision_id, reasons, policy_sha256 and the signed decision. On approval_required, poll the approval, then ask again with the same fields plus approval_id. An optional memo is sent only as memo_sha256, the SHA-256 of your memo.
2. Send it from your wallet
Only on allow, the answer adds payment: the USDC mint, the recipient wallet, the exact amount in base units (6 decimals), the network, a short reference, the wallets linked to the account that may send it, and transfer_call, an unsigned token transfer for your own wallet to sign and send. Trellis never signs or sends a payment transaction. A wallet is linked to the account when the account was created by wallet sign-in with it, or when it is the verified owner wallet of an organisation the account owns.
3. Confirm with the transaction
curl "$TRELLIS_URL/api/v1/agents/pay/$DECISION_ID/confirm" \
-H "Authorization: Bearer $AGENT_KEY" -H 'Content-Type: application/json' \
-d '{"tx_hash":"<transaction signature>"}'POST /api/v1/agents/pay/:decision_id/confirm with the same agent key reads that transaction from Solana and accepts it only when: the router finds the transaction on Solana by its signature; the transaction succeeded; and it holds a USDC token transfer from a wallet linked to the payer’s account, to the recipient wallet’s USDC account, for at least the allowed amount. A confirmed transfer is recorded as seen and becomes final once Solana finalizes it. A transfer from an unlinked wallet is refused with pay_wallet_not_linked. Other refusals are pay_tx_not_found (not confirmed yet, try again), pay_tx_failed, pay_transfer_not_found, pay_amount_short and pay_transfer_used (that transfer already confirms another payment). The amount actually paid is reported to the Guard decision as its executed outcome, so per_day_usd counts the real amount.
A confirmed payment is seen, waiting for finality, until its block reaches the chain’s finality point (ESCROW_FINALITY, with CHAIN_CONFIRMATIONS as a floor), then final. If the transfer leaves the canonical chain within ESCROW_REORG_HORIZON_BLOCKS, the payment and its receipt become reversed; a reversed payment still counts toward the daily limit. Re-checks happen when the payment is read (GET /api/v1/agents/pay/:decision_id, or the same confirm again) and every minute in the agent-pay-verify job.
The receipt
Each confirmation answers with a receipt whose payload has type trellis.agent.payment.v1: status, decision_id, policy_sha256, the payer’s account, agent key hash and wallet, the recipient wallet and profile id, the allowed and paid amounts, the network, tx_hash (the transaction signature), the instruction index, the slot and its blockhash, and verified_at. Check it with POST /api/v1/receipts/verify and {payload, sig, key_id}, like other signed receipts. The receipt is signed again whenever the status changes. It is the router’s statement of what it read on chain; the transaction itself is the proof of payment.
The payer’s account and, when the recipient is a Trellis agent, the recipient’s owner each get an inbox item, which the header bell shows. On /agents, the Pay another agent section walks through the same steps: pick a recipient from the directory or enter a wallet, enter an amount, see the rulebook’s decision and the instructions, send from a connected wallet or paste the transaction hash, then confirm and check the receipt.
const asked = await client.agent.pay({ to: profileIdOrWallet, amount_usd: "20" });
if (asked.decision === "allow" && asked.payment) {
const txHash = await sendFromYourWallet(asked.payment); // your wallet signs and sends the USDC transfer
const paid = await client.agent.confirmPay(asked.decision_id, txHash); // Python: client.agent.confirm_pay(...)
}Circuit breakers
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
An optional rulebook field, breakers, accepts max_spend_usd_per_minute (positive USD up to 1,000,000), max_requests_per_minute, max_denials_per_10min and max_distinct_models_per_hour (positive safe integers). Omitted fields add no restriction. AGENT_POLICY_ENABLED, default false, also controls breakers.
Switched on at trellis.example.
Before each policy admission, the router checks recorded rolling counters under the account lock. A value equal to or above a limit stops the agent with reason breaker: followed by the field name. That request receives HTTP 403 agent_killed before any reservation or charge. A trip overrides an on_breach action of deny and cannot permit anything another rule denies. These controls apply to requests through Trellis only, with no on-chain enforcement.
Spend is charged usage from the last minute plus open usage reservations. Requests and denials count policy admission batches; a batch with several models counts once, and every distinct requested model is observed, including denied models. An MCP tool admission and its routed inference are separate admissions. Approval-required attempts count as requests, not denials. Earlier decision events without a batch marker each count as an observation.
The principal resumes manually. Resume resets breaker observations and the spend window while leaving budget-cap spend intact; in-flight work may finish and later charges can trip the breaker again. Spend breakers also refuse an estimate that would cross the limit, and distinct-model breakers check the complete requested model set before admitting it. Equality is permitted for a new estimate or model set; the next admission trips at the recorded threshold. Final charges can exceed estimates; budget caps remain independent.
Breaker metadata uses the existing rulebook and event tables, with the same 90-day event retention. No prompt or response text is added. Ordinary inference paths still let Trellis’s router and the answering provider read request text in memory. The agent page includes breaker fields and a “Tripped by” badge.
Progressive autonomy
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
An optional autonomy rulebook field defines up to five ascending rungs. Each rung has integer after_days and clean_requests requirements, both nonnegative, and a strictly increasing caps_multiplier above 1 and at most 10. Requirements cannot decrease between rungs. Both requirements apply since reaching the current rung; the request counter starts again at every climb.
{
"autonomy": {
"rungs": [
{
"after_days": 1,
"clean_requests": 100,
"caps_multiplier": 2
},
{
"after_days": 7,
"clean_requests": 1000,
"caps_multiplier": 4
}
],
"demote_on": [
"deny",
"kill",
"breaker"
]
}
}The agent starts at rung 0 with caps ×1. The selected demote_on events return it to rung 0 and clear progress. A deny means a recorded policy refusal; kill means a recorded stop event; breaker means a recorded agent breaker event. Saving a rulebook restarts progress. Removing autonomy restores the original caps. Existing rulebooks without the field retain their canonical hash and behaviour.
Only per-request and rolling hour, day and week spending caps scale, using integer pico-USD arithmetic with fractional pico values rounded down. Output token limits, models, tools, lanes, UTC windows and approval thresholds never scale. A clean request is counted once per applicable rulebook after all policy checks allow it and its spending reservation succeeds; cached inference and allowed MCP tool checks also count. Dry runs, approval-required decisions, refused requests and failed reservations do not earn progress. This counts routing authorization, not successful provider delivery.
GET /api/v1/agents/me and each applicable rulebook in the agent list report autonomy with the current rung, since timestamp, clean request count, multiplier and next requirements with remaining days and requests; effective_caps reports scaled caps. A session and its parent advance independently and both must pass. The /agents page shows a ladder; configure rungs through the rulebook API. Editing other settings in the page preserves autonomy.
State comes from the metadata event chain, with rung, timestamp and counter checkpoints. Events normally expire after 90 days; active autonomy rulebooks retain their latest checkpoint and following events to preserve progress during inactivity. No prompt text enters these records. AGENT_POLICY_ENABLED defaults to false; it gates autonomy and all rulebook enforcement. These are router rules for requests through Trellis, with no on-chain enforcement. Trellis’s router reads ordinary chat text in memory on every lane; the encrypted-chat adapter forwards ciphertext.
Switched on at trellis.example.
Stop for a while
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Stop an agent for one hour, until tomorrow at 9:00 in your local time, or until you resume it. New requests through Trellis are refused during the stop. Requests already running may finish. After a timed stop ends, the next request resumes the agent and its other rules still apply. Keys following a playbook work the same way.
POST /api/v1/agents/:key_hash/kill accepts an optional until, an ISO time with a timezone, in the future and at most 30 days ahead. Omit it to stop until manual Resume. POST /api/v1/agents/:key_hash/resume clears the deadline. These calls require the same management key or team owner/admin as editing the target key. Session and inference-only keys cannot stop or resume agents.
GET /api/v1/agents/me and MCP trellis_agent_rules include stopped_until when the effective stop has a deadline. Individual policies also report it. If an inherited stop has no deadline, the combined stop has no deadline. Existing responses without a timed stop keep their fields. Read-only checks reflect expiry without writing; the next enforcement check clears the stored stop and appends one hash-chain event with kind resume and reason code scheduled, in the checking transaction. Manual Resume keeps its existing resumed event.
AGENT_POLICY_ENABLED defaults to false; agent routes return 404 while off. There is no timer worker or additional flag. Rules are enforced by the router only for requests through Trellis. The router reads request text in memory on ordinary inference paths.
Activity & receipts
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
GET /api/v1/activity is the account-wide list behind Activity in the dashboard: calls (with receipt ids and a link to check each receipt), agent approvals and rule decisions, alerts, deposits and balance changes, and agreement events, newest first in one item shape with exact USDC amounts. Filter with kind, key, model, from and to; page with limit (up to 100) and cursor; format=csv or json exports the filtered page. A key sees its own activity; management, owner and admin keys see the account within their team boundaries; never another account. GET /api/v1/inbox lists what needs attention or is new: pending approvals with their expiry, alerts, deposits, agreement events and status updates for hosts the account operates. The browser keeps the seen time; POST /api/v1/inbox/seen only returns it, and nothing is stored. Both need a key and are switched on at trellis.example.
GET /api/v1/agents/:key_hash/ledger lets the principal read a key’s activity. It uses the same account and team permissions as editing that key. GET /api/v1/agents/me/ledger lets an agent or session key read only its own activity. Both require AGENT_POLICY_ENABLED, which defaults to false; off returns 404.
Switched on at trellis.example.
Use from and to as ISO 8601 timestamps with an explicit timezone: from is inclusive and to is exclusive. Results are newest first, with up to 100 request rows, an opaque next_cursor and totals_per_day for the full date range in UTC. Send next_cursor as cursor for the next page. format=json returns rows and daily totals; format=csv streams this page, with X-Next-Cursor when another page exists. Downloads on /agents contain the selected page. CSV quotes cells and prefixes spreadsheet formula markers with an apostrophe.
Each correlated request includes its policy decision, model, lane, exact generation token counts, charged USD and pico-USD, signed receipt identifiers and links to the existing /verify receipt view and checker. Denied requests cost zero and have no receipt. Approval IDs are present only when an approval was used. Multiple models or inherited rulebooks share one row, with receipts, event_ids and policy_sha256s arrays; policy_sha256 is the first sorted digest. Costs come from generations, never estimates. An allow decision without a generation is not evidence that inference finished.
Existing records without explicit correlation are returned separately with unlinked=true; their policy, approval, or receipt association is not inferred. Historical generations have an allow label for recorded usage with no recorded rulebook decision. Policy decisions and their correlation metadata are retained for 90 days while the cleanup worker runs; generations keep their existing retention. Requests rejected before policy evaluation or generation creation have no row. The ledger stores no prompt or answer text. Trellis’s router reads ordinary chat text in memory, and rulebooks apply to requests through Trellis only, with no on-chain enforcement. Verify links do not certify a signature; use the existing receipt checker.
Agent alerts
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Add alerts: {} to a rulebook to enable owner alerts. Omitted alerts preserve existing behavior and rulebook hashes. Optional at_percent defaults to [80, 100]; denials_in_10min defaults to 5; channels defaults to ["webhook", "telegram"].
Cap percentages use rolling hour, day and week spend, including open reservations. Each threshold has a cooldown of that window’s duration, including across policy edits. Denied request batches trigger once per 10 minutes. Stops, whether manual or from on_breach, and newly created approval requests also add entries. Any breaker that stops the agent produces a stop alert.
Read GET /api/v1/agents/{key_hash}/alerts with the same principal permissions as editing the key, or open the feed on /agents. The feed keeps the newest 100 entries per account for up to 90 days. No prompt, answer, intent or arbitrary stop reason is copied. The router reads ordinary chat text in memory on every lane; the encrypted-chat adapter forwards ciphertext.
Delivery reuses enabled Spend Watch webhook destinations scoped to the agent or its account, and Telegram links authenticated as account management keys or same-team owners/admins. Spend Watch webhooks use guarded HTTPS egress and remain unsigned unless the optional signing feature is enabled and the owner rotates their secret. Read signing instructions. Email alerts are not switched on at trellis.example yet. Telegram alert delivery uses Trellis’s bot when the owner has linked it. Email has no linked account destination; without a selected linked channel, alerts remain in the feed only. TELEGRAM_LINKING_ENABLED (default false) adds account links through /agents or dashboard settings and /link in the bot; it requires the agent flag and bot token. This linking flow is switched on at trellis.example. Unlinking stops delivery through the account link; a separate chat-key connection remains until /forget.
AGENT_POLICY_ENABLED defaults to false; off means no alerts and this endpoint returns 404. Workers attempt delivery every minute, up to 10 notices per account per minute, at most 20 destinations per channel, with three attempts separated by five minutes. Successful destinations are skipped on retry; a crash between delivery and persistence may repeat a notice. Requests through Trellis’s router are the enforcement boundary; there is no on-chain enforcement.
Switched on at trellis.example.
Weekly agent summary in Telegram
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Link Telegram on Agents and choose “Weekly summary on Mondays” to receive last week’s agent spend, the five agents with the most spend, approvals, Stops and most-used model. Quiet weeks are skipped. Telegram can read the summary, including your agent names.
This feature is not switched on yet. WEEKLY_SUMMARY_ENABLED defaults to false and requires TELEGRAM_LINKING_ENABLED, AGENT_POLICY_ENABLED and a bot token on the worker. With the switch off, its routes return 404 and no summary job is registered. An hourly job sends on Monday from 09:00 UTC for the previous ISO week, Monday inclusive to the next Monday exclusive. Turn the toggle off or unlink to stop summaries.
GET /api/v1/telegram/weekly-summary reads opted_in and last_sent_week. PUT on the same path accepts only an opted_in boolean. Both require the same management or owner/admin key as Telegram linking, exclude session keys, return no-store, and require this key’s existing link (409 otherwise). Opt-in starts off for every link.
One summary goes to the first eligible opted-in link per account. Team administrators see only their current team’s agents. Totals read existing call charges; approvals count requests created that week, with their status at send time (“used” counts as approved). Stops count recorded stop events. Top model means most calls, with ties ordered by model id. Pending or expired approvals remain in the total. No new activity tracking is added.
The account keeps the last sent ISO week through unlinking and relinking. Ordinary retries and concurrent jobs do not repeat a successful week. A worker interruption or an uncertain network result after Telegram accepts the message can repeat delivery. Failed attempts retry later on Monday; there is no catch-up after Monday. Existing record retention and the link’s current access limit the summary.
Share a signed track record
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
POST /api/v1/agents/me/record-certificate with your agent’s Bearer key and {"claims":["requests_at_least:100","active_days_at_least:7"]} returns a certificate with a fresh random pseudonym, your requested true claims, issued_at, expires_at, key_id and an Ed25519 signature. Any false or insufficiently supported claim refuses the entire request with HTTP 422 record_claim_unproven. No agent key hash, account id, rulebook hash or underlying activity record is included. Issuance attempts are limited to five per minute per account across its keys.
Signed by Trellis’s router, which sees the agent’s activity; not a zero-knowledge proof. This describes records of requests through Trellis only. It establishes no on-chain enforcement and no activity outside Trellis. The router reads ordinary chat text in memory on every lane; the encrypted-chat adapter forwards ciphertext. This certificate path stores no prompt text, certificate, pseudonym or claims.
requests_at_least:N counts retained generation records for the calling key with a completion reason and no cancellation. active_days_at_least:D counts distinct UTC calendar dates with those records, rather than rounding elapsed time into days. Parent, sibling and child request counts are excluded. Missing or deleted records reduce the count. N and D must be positive integers of at most 15 digits; at most 16 distinct claims are accepted.
no_denials_days:D and no_kills_days:D cover an exact rolling interval of D × 24 hours, up to 90 days. They refer to retained rulebook denials (including denied approvals) and stop events. The key must predate the interval and have a current effective rulebook, including inherited parent rules, unchanged for the whole interval and currently not stopped. Recent edits, resumes or rulebook recreation conservatively refuse these claims. Parent events can include sibling activity and can also prevent issuance. Approval-required decisions alone are not denials. These claims describe the router’s retained rulebook history, not all authentication or provider failures. Autonomy rungs are unavailable here; rung_at_least is not accepted.
AGENT_POLICY_ENABLED defaults to false and gates issuance and public verification. Issuance also needs TLOG_ENABLED (default false), and waits for the reused receipt signing key’s receipt_key entry to appear in the key log. Certificates expire exactly seven days after issuance and are snapshots: later denials or stops do not revoke them. Signing key rotation keeps earlier public keys available. Key publication alone does not establish a witnessed checkpoint; check the log’s inclusion proof and witness policy separately.
Switched on at trellis.example.
POST /api/v1/agents/certificates/verify with the certificate as its JSON body returns {"data":{"valid":true,"notice":"…"}} only when its shape, signature, signing-key issuance window and expiry pass. No authentication is needed. GET accepts URL-encoded certificate JSON in the certificate query parameter; use POST to avoid placing it in URL history or upstream access logs. Malformed certificates return HTTP 400; expired or tampered certificates return valid:false.
For offline verification, obtain and independently trust or pin the router’s receipt JWKS from /.well-known/trellis-receipt-keys.json before going offline. Match key_id to kid and to the first 16 hex characters of SHA-256 of the raw public key. For key-log verification, hash that raw key and use /api/v1/tlog/proof?kind=receipt_key&sha256=… with a pinned log verifier and your witness policy. Retain the trusted keys and proof with the certificate.
import { verifyRecordCertificate } from '@trellis/client';
// trustedKeys is an independently trusted receipt JWKS saved beforehand.
const valid = await verifyRecordCertificate(certificate, { keys: trustedKeys });The helper verifies Ed25519 over canonical JSON of payload (recursive object keys sorted, no whitespace), requires the fixed certificate type and version, checks issued_at against the key’s valid_from and retired_at, and requires issued_at ≤ current time < expires_at with exactly seven days between them. It makes no network calls. A signature confirms what the router signed; it does not independently establish the underlying activity.
Each certificate has a new 256-bit pseudonym. There is no stable agent identifier across certificates, but the shared issuer signing-key id, selected claims and issuance timing remain visible and may correlate them. The authenticated router knows which key requested issuance; this is not anonymity from the router.
Opt-in public agent profiles
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
AGENT_PROFILES_ENABLED defaults to false. Switched on at trellis.example. With it off, profile APIs return 404 and the directory MCP tool is omitted. Apply the additive agent_profiles migration before enabling it. Rulebook categories require AGENT_POLICY_ENABLED; selected certificates also require TLOG_ENABLED and its existing signing configuration.
An owner or authorised account administrator publishes with PUT /api/v1/agents/:key_hash/profile. GET on the same path reads publication settings; DELETE unpublishes and deletes the row. Use an owner API key; session keys cannot manage profiles. The request accepts name (1–80 characters), description (up to 280), optional HTTP(S) homepage (up to 500, no embedded credentials), capabilities (up to 16 tags, 1–40 characters each), show (selected spending_caps, ask_first, kill_switch categories), and certificate_claims (up to 16 distinct supported record claims). Omitted selections default to empty.
Only selected rulebook booleans are returned, including applicable inherited rules. Exact spending amounts, approval thresholds, model and tool restrictions, policy hashes, stop reasons, key hashes and account identifiers are not automatically published. Owner-written names, tags, descriptions and homepages can identify their owner. Capabilities are supplied by the owner and are not verified abilities.
Certificate claims are checked against the selected key’s retained records and issued with a fresh pseudonym. Updates replace the selected certificate; empty claims remove it. Public reads verify its signature, signing-key issuance window and expiry. Expired or invalid certificates are omitted. The card adds valid:true as read-time metadata; remove valid before passing a certificate to strict certificate verifiers. The profile page’s certificate JSON already removes it. These seven-day snapshots do not revoke on later activity, do not independently prove the underlying observations and are not zero-knowledge proofs. Publishing intentionally links the selected certificate to the public profile. Issuance shares the account’s five-per-minute certificate limit.
GET /api/v1/agents/profiles/:slug returns an A2A-style card with name, description, url, capabilities, provider organization Trellis, optional homepage and a trellis extension containing id, rulebook_summary, certificates and status. This is a discovery card, not an agent invocation endpoint or a complete A2A protocol implementation. The discovery card reports agent hardware attestation as unavailable; inspect registered sealed-agent evidence on /agents separately. Sealed hosting is available, but no sealed agent is registered at trellis.example yet.
GET /api/v1/agents/profiles accepts an exact tag, a cursor and limit (1–50, default 20), returning data and next_cursor. The MCP tool trellis_agent_directory accepts the same fields and needs no API key. Disabled or expired keys are hidden. Public profile slugs are independent random 144-bit identifiers; republishing after deletion creates a new slug. A random slug does not prevent correlation through owner-written fields or timing.
Publish and search profiles; individual pages use /agents/profile/?id=<slug> and fetch current cards. Unpublishing removes router discovery immediately, but cannot remove copies already retained by public readers or database backups. Profiles do not change who can read inference: ordinary chat requests are read in router memory on every lane; the dedicated encrypted-chat path forwards ciphertext.
Sealed agent hosting
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Sealed agent hosting is available at trellis.example, but no sealed agent is registered there yet. The owner builds and publishes the agent sidecar image. The approved recipe in deploy/agents/sealed runs an owner’s agent image pinned by digest with a credential proxy inside an Intel TDX dstack confidential VM. The proxy derives an application-scoped sealing key from the guest agent using a path containing the measured compose hash, and seals the dedicated Trellis API credential with AES-256-GCM. The credential is provisioned through stdin inside the confidential guest, never in the compose manifest. The same measured app can recover it after restarts; manifest changes require fresh provisioning and a fresh dstack app identity. GetKey paths are caller-selected: KMS authorization must restrict release to the approved measurement. Giving replacement code the old application key could let it request the old sealing path.
With the principal’s Bearer key, POST /api/v1/agents/{key_hash}/sealed with attestation_url (HTTPS /attest without query or credentials), agent_image_digest and compose_hash (both sha256: followed by 64 lowercase hex characters). Approve the exact compose manifest and both container image digests independently. The target must be an active key without management permissions. DELETE the same URL removes the registration.
The router obtains a fresh nonce-bound TDX quote over pinned TLS. Its report_data commits canonical JSON of type, agent_image_digest, compose_hash, agent_key_hash (SHA-256 of the API credential), sidecar_version and tls_spki_sha256, followed by the 32-byte nonce. All configured quote verifiers must accept it, and a dstack verifier must recover the approved measured compose hash. Debug-enabled TDX, key mismatch, TLS mismatch and stale nonce evidence are refused. Image identity is established by approving the digest-pinned measured manifest, not by trusting a self-reported image label alone.
AGENT_SEALED_ENABLED defaults to false and requires AGENT_POLICY_ENABLED (default false), plus ATTESTATION_VERIFIERS including a configured dstack verifier. Existing verifier settings apply: DSTACK_VERIFIER_URL and any other selected verifier credentials. The existing attestor worker rechecks at ATTESTATION_INTERVAL_MS (default 600000). A failed check clears the badge; success expires after 30 minutes even without workers. The agent list and GET /api/v1/agents/me include sealed metadata only while the feature is enabled. The badge reads “Sealed · attested · image sha256:…”.
Trust includes Intel TDX, firmware, the guest OS, dstack KMS authorization, quote-verifier services and code inside the measured VM. Measured does not mean audited: guest administrators and approved code can read or exfiltrate secrets. Rollback, denial of service and all side channels are not prevented. Owners may retain a credential copy; this badge does not establish exclusive possession or prove that every later request came from the VM.
The agent container does not receive the API credential. The proxy sends it to Trellis as HTTPS Bearer authentication and forwards request and response streams, including receipt, lane and policy headers. Ordinary requests sent to Trellis are read by the router in memory on every lane. Only the encrypted-chat transport keeps message plaintext off that router when the agent explicitly uses it; sealed hosting alone does not enable encrypted chat.
The router keeps the registration URL, expected deployment hashes, random revision, fixed result code, verifier names, TLS key hash and check timestamp in its existing key-value store. No quote or API credential is persisted by this registration path. Removing the registration deletes the row; disabled features leave it stored until removal. The guest keeps the encrypted credential file and reads credentials and forwarded bodies in memory. What we keep
The open host network.
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Trellis Network is open for early hosts running deploy/network/approved/tdx-qwen2.5-0.5b: Intel TDX in a supported confidential VM serving Qwen2.5 0.5B. Join with one command. Admission is automatic after fresh hardware evidence, the signed host policy v1 and sanctions screening of operator and payout addresses pass. The policy is published at GET /api/v1/network/policy and committed as a host_policy entry in the key log.
New hosts start on probation, with a public record on Hosts. Sidecar bindings v2 commit the source archive hash, engine image and served model ID into report data. Legacy v1 evidence still verifies but does not supply every field this admission policy requires. These bindings do not prove that a declared engine image is running or that a source archive produced it; appraising the measured deployment remains necessary.
Hosts post no bond or deposit at trellis.example: admission is by hardware attestation, and traffic follows each host’s record. Payouts and slashing are not switched on at trellis.example yet. No payouts are being made. Read the host policy and limits.
A host is one of two kinds of supply for the attested lane. The other is an attested gateway, a provider’s confidential endpoint that the router verifies and pays per token, which needs no host of your own. What each kind proves differs: read the two kinds and their limits.
Self-serve host signup
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
NETWORK_HOSTS_ENABLED defaults to false; signup and status return 404 while disabled. Enabling it requires NETWORK_POLICY_ENABLED and TLOG_ENABLED. Production also requires Redis, hardware quote verifiers over HTTPS, a persistent log signing key and the existing independent checkpoint checks. Publish a signed host policy before admission.
Switched on at trellis.example.
Send POST /api/v1/network/hosts with {name, endpoint, payout_address, models, contact?}. Name is at most 60 characters, models contains one to eight distinct IDs, and optional contact is at most 120 characters. Endpoint is the sidecar root URL over HTTPS, without credentials, query or fragment; the router calls its public /attest endpoint. HTTP submissions are recorded as rejected without contacting the endpoint. Private and reserved network destinations are refused by the existing provider transport in production.
Use the X-Wallet-Auth: address:unixSeconds:signature header of a wallet-signed request. Sign the six lines trellis:wallet-auth:v2, the method (POST for signup, PUT for the credential), the router's host, the request path, unixSeconds and sha256(canonical JSON body), joined by line feeds, with the operator wallet's ed25519 key (a Solana signMessage over the UTF-8 bytes; the signature is base58). Canonical JSON: recursively sort object keys, retain array order, encode UTF-8 without whitespace. Signatures expire after five minutes, are single-use, and are good only for that method and path at that router; the earlier trellis:unixSeconds:sha256 message is no longer accepted. The join.mjs command signs this for you. Signup is limited to three attempts per wallet and ten per network address per minute; onion requests use the existing shared scaled bucket. The temporary address counter lasts 61 seconds in Redis.
The response contains provider_id, status, plain-English reasons and a dashboard link. A new wallet and endpoint pair returns 201; re-applying to the same pair updates it and returns 200. The wallet becomes the lowercase operator, with USDC payout mode. Fresh hardware evidence must pass the existing attestor, the published policy and sanctions screening when enabled. Development evidence is refused. Success records probation for NETWORK_PROBATION_DAYS (default 7); refusal records rejected. Both operator and payout wallets are screened.
GET /api/v1/network/hosts/{provider_id}/status returns status, reasons, fresh attestation state, probation end and weight. Weight is the current network selector multiplier, rounded to two decimals: the highest across eligible model offers, not a traffic percentage. It is zero without eligible offers or fresh healthy evidence. With offer terms in the signed policy, the registry creates shadow offers for requested quote-bound models; fresh healthy probation hosts receive a reduced routing multiplier of up to 0.1 through the existing selector. Payouts to network hosts are not switched on yet. A policy refusal can coexist with a successful hardware check; inspect the reasons. The approved recipe, deploy/network/approved/tdx-qwen2.5-0.5b, uses Intel TDX in a supported confidential VM and SHA-256 sidecar bindings v2. These commit the source archive hash, engine image and served model ID alongside existing digests. Admission is automatic after the fresh quote, signed host policy v1 and operator/payout sanctions checks pass. Probation has a public record on Hosts. Legacy v1 evidence still verifies but lacks the fields this admission policy requires.
Signup needs no inference API key from the router. The host operator generates its own high-entropy key and configures its SHA-256 through the sidecar’s auth.keys flow. To supply it securely for later inference, send wallet-authenticated PUT /api/v1/network/hosts/{provider_id}/credential with {provider_id, api_key} over HTTPS. The signed provider ID must match the path and recovered operator wallet. The router stores it only in the existing AES-GCM encrypted provider-key column, never returns it, and retains it on re-application. Rotate it by repeating this endpoint and updating the sidecar’s hash. Protect the operator’s key and router APP_SECRET.
Download and inspect join.mjs; compare its digest on the registration page. Add --api-key-file /path/to/sidecar.key to signup to supply the credential after a successful response, or use --credential-only PROVIDER_ID --key-file /path/to/operator.key --api-key-file /path/to/sidecar.key later. --api-key-env NAME reads an environment variable instead. The UTF-8 key is trimmed to 16–500 characters; POSIX files must not be group or world readable. --dry-run reads neither key, prints canonical bodies with api_key as <redacted> and uses <provider_id> until signup assigns the ID. A credential failure leaves signup in place; retry with credential-only mode using the same operator wallet.
The router retains the submitted host settings, optional contact, wallet and payout address, admission reasons and existing attestation records. Status is public by ID; contact and credentials are not returned there. Ordinary chat reads request text in router memory on every lane; the encrypted-chat adapter forwards ciphertext. Admission does not change that. Read the data inventory.
With NETWORK_HOSTS_ENABLED=true, scheduled attestation renews probation hosts against the current signed host policy without promoting them to live. A failed renewal blocks selection and appears on Hosts; revoked bindings reject the host and disable its offers. Admission records retention as attested, sourced to the checked host policy version, while jurisdiction, legal hold and training use remain undeclared. Fresh evidence and eligible offers are required for the attested lane. Rejection removes this disclosure profile. The router reads ordinary chat text in memory on every lane; the encrypted-chat adapter forwards ciphertext.
Network host policy
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
When NETWORK_POLICY_ENABLED is on (default false), GET /api/v1/network/policy returns the current policy, and GET /api/v1/network/policy/{version} returns an immutable version. Each response includes the canonical JSON, its SHA-256, an Ed25519 signature over those UTF-8 bytes and the log verifier key. Pin that key independently; a key returned beside a signature does not establish the operator’s identity. The host_policy entry in the transparency log names the version and hash. Check its inclusion under a signed checkpoint and the independent witness or public-log evidence.
Switched on at trellis.example.
An admin publishes a complete document through POST /trpc/network.publishPolicy with the operator token. Versions start at 1 and advance consecutively; existing versions cannot be replaced. Publication requires TLOG_ENABLED and the production log signing key and independent checkpoint checks already required by the log. Nothing is seeded automatically. Run scripts/network-policy.ts with --base, --provider and --model-id to draft from the router’s current public attestation record, then supply the reviewed source and engine pins and confirm GPU CC requirements before publication.
The pure check compares verified, quote-bound sidecar image and source hashes, engine images, model IDs and digests, and TEE kind. Development evidence is always refused. GPU models require GPU CC evidence verified separately from CPU attestation. Opt-in SHA-256 sidecar bindings v2 commit the source archive hash, engine image and model ID in addition to image, compose and model digests. Legacy v1 still verifies, but its missing policy-required fields fail admission. The live policy v1 approves deploy/network/approved/tdx-qwen2.5-0.5b: Intel TDX in a supported confidential VM serving Qwen2.5 0.5B. A compose hash is required as an existing binding, but this document does not approve a compose manifest. This policy governs automatic network host admission and renewal; it does not replace other provider admission paths. Digest bindings are software statements inside a verified quote; they do not establish that source produced an image or that running software obeys a data policy. Trellis’s router reads ordinary chat text in memory on every lane; the encrypted-chat adapter forwards ciphertext.
Each models entry may include an optional strict offer object: slug (lowercase catalogue namespace/model), name, optional hugging_face_id, context_length, max_completion_tokens, optional quantization, and pricing with positive decimal strings prompt and completion in USD per token. Names and identifiers are bounded to 160 characters, quantization to 32, prices to 32 characters and at most 1000000 USD per token, and token limits to 2147483647. Omitting offer leaves existing canonical bytes and hashes unchanged. With NETWORK_HOSTS_ENABLED, successful admission copies terms only for models both requested and bound to the verified quote. The registry creates shadow offers during probation; models without offer terms create none. Existing lane and attestation freshness checks still apply: the attested lane also requires an operator-declared attested-retention profile; the public lane can select fresh attested network hosts under its existing rules. Probation starts with routing weight 0.1; failed or stale hardware evidence excludes the host. Rejection clears terms and disables retained offers.
Network host payments
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Payouts are not switched on at trellis.example yet. No payouts are being made.
How payouts work
When enabled, hosts are paid per token served only from receipts included in their confirmed per-host roots. Weekly USDC payments are made at the host’s full price: the network fee is 0 (zero markup). Accrual is switched off by default; runtime availability is reported by network.payouts_open in GET /api/v1/status.
Settings
| Setting | Default | Notes |
|---|---|---|
NETWORK_PAYOUTS_ENABLED | false | Needs sanctions screening, host anchoring and a settlement worker signer when switched on. |
NETWORK_FEE_BPS | 0 | Bounded to 0–2000. The configured percentage is shown at runtime. |
Unresolved or reverted payouts require operator reconciliation.
Network statistics
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
GET /api/v1/network/stats is public and read-only when NETWORK_STATS_ENABLED is true (default false). Switched on at trellis.example. Token activity currently shows “No data yet”. No API key is required. The network page fetches statistics in the browser; its static export renders without the API.
The response has a data envelope: as_of, cache_seconds, hosts (total, probation, live and rejected), attested_hosts, capacity (distinct model count and IDs), tokens, bonds, interest and policy_version. Host status counts include network hosts only. Other statuses contribute to total but not the three named counts. Attested hosts require admission evidence, fresh successful hardware attestation and a fresh successful latest attempt. Models must have eligible offers and be among that host’s admitted model IDs; model count is not GPU memory or throughput.
tokens.public_lane.days_7 and days_30 contain decimal-string lower and upper_exclusive bounds in 100,000-token buckets. They count input plus output tokens from retained public-lane generation records on network hosts, excluding cache hits and future records. These coarse ranges are not differential privacy and cannot establish complete historical coverage after records expire. Null means no records in that window.
tokens.private_lanes is null. The existing DP releases at GET /api/v1/stats cover router-wide private-lane traffic, without a host dimension or 7/30-day history; they cannot be assigned to network hosts. Private-lane billing rows are excluded from this endpoint.
Bonds reuse the bond indexer’s total and active amounts as decimal strings in USDC base units (6 decimals), with freshness and indexed block. Null means indexing is not enabled; host bonds are switched off at trellis.example, so it is null there. Stale index data remains identified as stale and is not shown as a current amount on the site. Interest reuses waitlist counts by role, region and readiness mentions; these are self-reports, not eligibility. Policy version comes from the published host policy, or is null if unavailable or disabled.
Snapshots are cached in router memory for at most 30 seconds. HTTP freshness uses the remaining snapshot lifetime. A failed refresh returns 503 with no stale snapshot. Disabled deployments return 404. No new database rows, Redis keys, request-body readers or address readers are added. The router still reads ordinary inference request text in memory on every lane; these statistics make no additional prompt-privacy claim.
Public host records.
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Hosts lists providers with a hardware verification record. GET /api/v1/hosts returns public identity, hardware status, probation and models. GET /api/v1/hosts/{providerId} adds the existing attestation status and paged history, current and superseded build measurements with Rekor links, per-host receipt-root counts and the latest root, observed uptime, proof-time and coarse invoice bands.
The API is available when HOST_DASHBOARD_ENABLED=true (default false). The static page reads the host id from /hosts/?id={providerId} or /hosts/#{providerId} and uses the same origin, including over onion. A stale host remains inspectable, with no current hardware verification claim.
Public earnings are lifetime USDC settlement invoice bands after provider fees, including paid invoices and excluding the open hour. They are not a real-time payout balance. Exact lifetime and unpaid invoice units, payout mode and payout address appear only in an operator response. USDC has six decimal places. An unpaid invoice has no recorded payment transaction; a pending payout may already be processing.
To request the operator view, sign a wallet-signed request with the operator wallet's ed25519 key (Solana signMessage; base58 signature): the six lines trellis:wallet-auth:v2, GET, the router's host, the path /api/v1/hosts/{encodeURIComponent(providerId)}, {unixSeconds} and {sha256(scope)}, where scope is exactly GET /api/v1/hosts/{encodeURIComponent(providerId)}. Send X-Wallet-Auth: {address}:{unixSeconds}:{signature} with the GET. The router uses walletAuth’s five-minute window and replay protection, then compares the recovered wallet with the stored host operator. Signatures for other resources, other methods or another router are refused. Detail responses use Cache-Control: no-store; the list is public.
A confirmed root with a recorded transaction is reported as anchored on chain. A root kept off chain says so; pending roots are awaiting confirmation. Uptime is the measured success rate of requests and probes across served models, not continuous availability. Proof-time counts periods holding fresh router-verified hardware evidence, with earlier unrecorded time unknown. Build measurements establish recorded digests, not build admission approval, source equivalence or prompt handling. Trellis’s router reads request text in memory on every lane today. These views add no table, money logic, log field or key family; signed access reuses the existing wallet-auth replay marker described in What we keep.
Host bonds
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
A Graft host on SEALED or BLIND posts a USDC bond in the trellis_bond program: HostBond{host, amount ≥ 10,000 USDC, unbond_at, strikes}. An attested gateway, the other kind of supply on those lanes (Lanes), posts no bond: it is held to its attestation and its signed receipts, and one that fails attestation is dropped from the lane. The bond is what makes a wrong answer cost the host more than the call paid: slashes refund the affected callers first, and the rest goes to the treasury.
| Evidence | Slash |
|---|---|
| Empty-200 answers above 2% over 24 hours | 1% |
| Quantization swap (3 of 3 canaries) | 25% and delisting |
| Uptime below 95% over 30 days | 0.5% per day |
| Shadow re-execution mismatch | 50% and ejection |
| SEALED served without a fresh attestation | 5% per incident |
| Capacity commitment under-delivered | the purchase price of the unserved Bushels |
A slash is proposed by the slasher key and can be executed after a 72-hour public dispute window. A dispute filed inside the window blocks execution until the program's authority resolves it or 7 days pass, whichever comes first. One proposal takes at most 50% of a bond, and all rate-based slashes of one bond within 30 days take at most 50% of it together; what that cap cuts off is not carried over. A slash the cap cuts to nothing neither delists nor ejects the host. Delisting and ejection are lifted only by the program's authority, through a proposal that waits 24 hours on chain. Unbonding takes 14 days. A capacity commitment locks its value in the bond, at the grade price of the moment the host made it, until its claims are paid or expired, and that part cannot be withdrawn. Claims for a commitment that fell short are paid out of that lock: together they never exceed what the host locked for it, whatever the grade prices are changed to afterwards.
Who can change what
The program's authority is a single operator key until it is handed to one Squads 2-of-3 multisig. A guardian key, separate from both, can pause new bonds and nothing else: it cannot unpause, cancel a proposed change or move funds, and a pause lapses after 72 hours unless the authority renews it. request_unbond and withdraw_bond cannot be paused. Loosening a setting, replacing a role key or a payout account, or handing over the authority takes effect only after a 24-hour delay on chain, with the new authority accepting; tightening is immediate. The delays have floors compiled into the program: the dispute window is at least 72 hours, a dispute blocks for at least 7 days and unbonding takes at least 14 days. The programs are unaudited.
Instructions
post_bond(amount)- moves USDC from the host's token account into the bond vault; the first post needs at least 10,000 USDC.
request_unbond()- starts the 14-day unbond period; the host keeps serving and stays slashable until it ends.
cancel_unbond()- withdraws the request and keeps the bond active.
withdraw_bond()- returns the bond after the unbond period, less any slash executed in the meantime and less what is locked behind open capacity commitments. It is refused while a slash proposal is open.
propose_slash / dispute / resolve_dispute- the slasher key named in the program's config proposes a slash with evidence; a 72-hour public window lets the host dispute; a dispute blocks execution until the program's authority resolves it or 7 days pass.
execute_slash()- anyone can send it once a proposal is executable, with one exception: a slash that the 30-day cap would cut is executed by the slasher key only, so nobody can run it at the moment it takes least. Funds move only to the configured payout accounts.
propose_reinstate / resolve_reinstate- the program's authority proposes to list a delisted or ejected host again and applies it no sooner than 24 hours later; a slash executed in between makes the proposal stale.
Posting a bond is done from the operator's own wallet or a script against the program (the program id is in GET /api/v1/status under chain.programs.bond); this site shows bond state and moves no funds. The host record lists the bond beside the attestation and uptime evidence.
Holder tiers
Built, not enabled at launch. Reading the tier table is served, and it reports that no tier is set. Tiers, their perks, your own tier, polls and votes are not served on the core launch surface.
A holder tier is a membership level for a wallet that holds $TRLS. Each tier has a fixed threshold, and a wallet has the highest tier whose threshold its balance reaches. Holding more inside a tier adds nothing. A tier gives access and priority; it does not change a price. Trellis adds no markup, so every caller pays the host’s price whatever their tier, and a tier pays nothing to its holder. This section describes what the router does today; thresholds and perks can change. No thresholds are set at trellis.example yet: until they are, enabled is false and the holder tiers page says so.
What a tier can give, each set per tier:
- Higher limits. More requests and tokens per minute, and more agent keys, saved routes and batch rows. A tier does not lower a limit.
- Sealed-lane priority. When a sealed host is full, waiting calls are admitted by tier priority, then in order of arrival. The same priority orders Bushel purchases when a sale has more requests than capacity. A share of sealed capacity is kept for callers with no tier, so they are not left waiting behind tiers.
- Early access. A newly listed model can open to tiers first, inside a window of up to 48 hours. Higher tiers get in earlier.
- Advisory votes. One vote per wallet on which models get listed and on slashing rules, with a fixed weight per tier.
- Credits that do not expire. While a wallet holds a tier with this perk, the router leaves that key’s credits in place when it would otherwise send an expiry notice or sweep.
- Profile badge. An opt-in badge with the tier’s name on a public agent profile. It is off until the owner switches it on.
Reading the tiers and your own
GET /api/v1/holders/tiers is public. Its data holds enabled, token (address, symbol and program, or null), cache_s and tiers, lowest threshold first. Each tier has name, min (the threshold, a decimal string in whole tokens), rpm_multiplier, tpm_multiplier, max_agent_keys, max_saved_routes, max_batch_rows, sealed_priority, early_access_hours, vote_weight, credits_never_expire and badge. No field is an amount of money. When enabled is false, show “Holder tiers are not switched on yet”.
GET /api/v1/holders/me takes a Bearer key and answers for the wallet behind it. Only a wallet sign-in key has a wallet; any other key gets the same shape with wallet: null and a hint. The answer holds enabled, token, wallet, balance, balance_error, tier (a tier or null), next_tier (name, min and remaining, or null) and perks: the limits this key runs under now (rpm, tpm, agent_keys, saved_routes, presets, batch_rows; 0 means no cap), sealed_priority, early_access_hours, vote_weight, credits_never_expire and badge.
The tier is read from the wallet’s $TRLS token account (Token-2022) and cached for about an hour, so a change in balance can take that long to show. If the balance cannot be read, balance_error is true and no tier applies until it can.
Early access to newly listed models
While a model’s early-access window runs, its entry in GET /api/v1/models carries early_access with until, when the model opens to everyone, and your_access_at, when it opens to the caller. Send your key to get your own time; without one, both are the same. Outside a window the field is null. The models page shows the same times as a label on the model.
A call to a model that is not open to the caller yet is refused with 403 and error.type: "early_access". Its metadata holds model, opens_at, early_access_until and tier (your tier’s name, or null), and Retry-After gives the seconds until it opens to you. Nothing is charged for the refused call. When a request names fallback models, a model still closed to the caller is skipped and an open one serves the request. Early access decides when a model can be used, never what it costs.
Advisory votes
Built, not enabled at launch. Polls and votes are not served on the core launch surface.
Polls ask which model to list next or which slashing rules to adopt. They are advisory: a result informs a decision and does not carry it out. GET /api/v1/holders/polls lists polls (add ?status=open or ?status=closed), and GET /api/v1/holders/polls/:id returns one. A poll has id, kind (model_listing or slash_schedule), title, options, status, created_at, closes_at, closed_at, advisory: true and results: per option votes and weight, plus total_votes, total_weight and final. Tallies are public; who voted is not shown.
To vote, send POST /api/v1/holders/polls/:id/vote with the body {"poll_id": "…", "option": "…"} and an X-Wallet-Auth header of <address>:<unixSeconds>:<signature>. The wallet signs a wallet-signed request: the six lines trellis:wallet-auth:v2, POST, the router's host, the vote path, <unixSeconds> and <sha256 hex>, where the hash is over the canonical JSON of the body (keys sorted, no spaces). The path and the body both name the poll, so a signature cannot be used on another one, and a vote signed for one router is not a vote at another. A recorded vote answers 201 with poll_id, option, tier, weight and voted_at.
Each wallet has one vote per poll and cannot change it. The weight is the tier’s fixed vote_weight, never the balance. When a poll closes, every voter’s balance is read again; a wallet that has dropped below the tier it voted with counts with the weight of the tier it holds then, or not at all with none. Refusals: 403 not_a_holder (no tier with a vote), 409 already_voted, 409 poll_closed, 401 invalid_wallet_auth and 503 balance_unavailable.
Profile badge
The profile editor in the agent directory has a “Show a holder badge” switch, sent as show_holder_badge on PUT /api/v1/agents/:key_hash/profile. It is off by default because a badge shows the tier of the wallet behind the profile. When it is on, and the key belongs to a wallet sign-in account whose wallet holds a tier with a badge, the profile card and the directory show trellis.holder_badge with the tier’s name. The wallet address and the balance are never shown.
SDKs
The TypeScript and Python SDKs have holders.tiers(), holders.me(), holders.polls() and holders.vote(pollId, option, signer). The vote helper builds the body and signs the header with the wallet signer you pass.
Run a provider
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
Most routers do not need a host of their own for the attested lane: an attested gateway serves it per token, with no hardware to rent (Lanes). Running a provider is the self-hosted path, for an operator who brings a confidential VM. A small CPU confidential VM with a tiny model is enough to exercise admission; a confidential GPU is only needed to serve a real model on your own host.
A provider serves an open-weights model behind the Graft sidecar inside a confidential VM (Intel TDX, with the GPU in confidential-computing mode where the hardware supports it). At boot the sidecar hashes the served weights against an allow-list, generates its TLS, receipt and HPKE keys inside the enclave and produces a TDX quote whose report data binds those keys and the image, compose and model digests. The router verifies that quote with a fresh nonce before it routes an attested request to the host, and again on a schedule; the proof-time panel shows how recent each verification is.
The install package in deploy/graft/ has a one-command installer, a Compose file, a Helm chart and Terraform modules, and the graft CLI (init, add-node, verify, status) checks a node before it is registered. Registration on this router goes through the host signup script with an operator wallet, under the host policy; a bond in USDC backs the host’s answers. The approved build for early hosts is deploy/network/approved/tdx-qwen2.5-0.5b. The providers page lists the hosts the router currently sees and what each one has proven.
Attestation badge
Built, not enabled at launch. A router on the core launch surface does not serve this. Where the text below says a feature is switched on, it describes a router that runs the full surface.
/badge.js shows a provider's or a model's verification status on your own page. It reads the router's public records from the viewer's browser (the attestation record, its history and the catalog), checks that they agree and are current, and shows only what every check backs: Attested, Policy, Vendor-forwarded or Unverified, with the first characters of the verified measurement and the share of the last seven days with a fresh attestation. No dependencies, no cookies, no tracking. The hardware quote itself is verified by the router, not in the browser, and the badge says so.
<script src="https://<router>/badge.js" data-endpoint="<provider id or author/model>" data-theme="auto" async></script>
<!-- or a plain image, rendered by the router -->
<img src="https://<router>/api/v1/badge/<provider id>.svg" alt="Trellis attestation status">GET /api/v1/badge/{id}.svg renders the same status as an image for an <img> tag or a Markdown image, with no script; an unknown id is still an image, reading Unverified.
What’s new
Payments on Solana (prepaid credits, tabs and the x402 facilitator), host bonds, agent rules, Telegram linking and approvals, opt-in public profiles and encrypted chat are documented below. Sealed agent hosting is described, but no sealed agent is registered at trellis.example yet. USDC deposits and tabs are not switched on at trellis.example yet; the network is open for early hosts running the approved build.
- Payments on Solana
- Pay by tab
- x402 facilitator
- Host bonds
- Holder tiers
- Early access to new models
- Advisory holder votes
- Review unused keys
- Proof pack
- Deposit countdown and credit notices
- Similar models when a model is unavailable
- Stop for a while
- Balance runway and alerts
- Spending limits
- Default route
- Lane report
- Starter setups
- Auto top-up
- Replay your rules
- Playbooks
- Rulebooks in plain English
- Agent rulebook
- Ask-first approvals
- Allow this next time
- Pay another agent
- Decision tags
- Circuit breakers
- Progressive autonomy
- Activity & receipts
- Agent alerts
- Weekly Telegram summary
- Track-record certificates
- Public profiles & directory
- Sealed agent hosting
- Encrypted chat
- Host signup
- Host policy
- Host payouts
- Live network statistics