Yinsi is a TypeScript-first monorepo: a Next.js app (this site) and four packages — @finch/sdk, @finch/providers, @finch/flightpath, @finch/db. There is no onchain program to build or deploy.

# in the monorepo root
npm install

# server-side environment (never client-side)
# GROQ_API_KEY=…             model compute (free tier); OPENROUTER_API_KEY=… also free
# HYPERBOLIC_API_KEY=…       paid alternative, used only when no free provider is set
# MONGODB_URI=…              optional: registry + memory + ledgers
# SOLANA_RPC_URLS=…          optional locally; the public mainnet RPC is rate limited

npm run dev        # web app on http://localhost:3000
npm run typecheck  # all workspaces

Then launch your first agent — observer mode, read-only, safe by default:

import { createAgent, hyperbolic } from "@finch/sdk";

const agent = await createAgent("first-agent")
  .describe("Reads balances and reports. Nothing more.")
  .model(hyperbolic("meta-llama/Llama-3.3-70B-Instruct"))
  .memory({ kind: "ephemeral" })
  .tools("balance_native", "token_data")
  .wallet({ mode: "observer" }) // read-only — the safe default
  .launch();

const result = await agent.run(
  "What are the decimals, supply and mint authority of EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v?",
);
console.log(result.output);
console.log(result.steps); // every model + tool step, logged

An agent is a portable manifest — a finch.manifest/0.1 document: identity, model, memory, tools, permissions, wallet, triggers, budget, deployment, publisher, endpoints, IO schemas. The fluent builder and the visual agent builder emit the same document, and hatch() launches it against live infrastructure. Manifests cannot widen their own permissions: write tools are stripped unless the wallet grants operator mode, RWA interactions are always registry-limited, and simulation is not optional.

// Launch a manifest built in the visual agent builder (/app/build):
import manifest from "./market-watcher.manifest.json";
import { launchFromManifest, hyperbolic } from "@finch/sdk";

const agent = await launchFromManifest(manifest, {
  provider: hyperbolic(manifest.model.model),
});

Runs return a full trace: output, steps, executions (execution-layer records), usage, and a haltedBy reason — including the kill switch.

The execution layer (@finch/flightpath) is how agents reach Solana: SOL and SPL balances and transfers, SPL approvals, single instructions to allowlisted programs, Jupiter swaps, token, market and portfolio reads, and approved RWA interactions. An intent carries the exact instructions it will execute, and the policy engine decodes those instructions — not the intent's summary — before anything else happens. Every write follows one path — policy → simulate → (approve) → sign → submit → confirm → log — and produces an idempotent ExecutionRecord.

// Operator mode: bounded writes. The key comes from the RUNTIME env —
// it is never part of a manifest and never the fee wallet's key.
import { createFlightpath } from "@finch/flightpath";
import { createAgent, hyperbolic } from "@finch/sdk";

const flightpath = createFlightpath({
  // base58 64-byte secret key, or a JSON array of 64 numbers
  operatorKey: process.env.FLIGHTPATH_OPERATOR_KEY,
});

const agent = await createAgent("payments-runner")
  .model(hyperbolic("Qwen/Qwen3-235B-A22B"))
  .tools("balance_native", "transfer_native")
  .wallet({
    mode: "operator",
    allowances: [{ asset: "native", perDay: "0.1", perTx: "0.02" }], // SOL
    allowedPrograms: [],            // plain transfers need none; program_invoke and swaps do
    allowedRecipients: ["<an address you trust>"],
    approvalThreshold: 0.5,
  })
  .launch({ flightpath });

// every write: policy → simulate → (approval) → sign → submit → confirm → log

Simulation is simulateTransaction against current state; a failure stops the intent there, with the program logs that explain it. The signature comes from the operator keypair (FLIGHTPATH_OPERATOR_KEY, runtime only) or, on this site, from the visitor's own wallet — see User-signed execution. A write counts as done only when the network confirms the transaction, and only a confirmed one gets an execution proof.

The execution layer targets Solana mainnet-beta by default. SOLANA_CLUSTER selects devnet or testnet, SOLANA_RPC_URLS lists provider endpoints tried in order — the public mainnet endpoint is the fallback, and it is rate limited — and FLIGHTPATH_FORCE_DEV=1 switches to a labelled devnet target for testing. Yinsi deploys no program of its own: the registry is signed memo transactions on Solana.

These are the tools a manifest can name. The table is generated from FLIGHTPATH_TOOLS in @finch/flightpath — the same list the runtime hands to models and the agent builder renders — so it cannot drift from the code. Reads carry no risk. Writes are simulated first, checked against the wallet policy, and logged; an agent in observer mode never sees them.

The model layer is a provider abstraction. Hyperbolic serves compute first (hyperbolic(model)), and openAICompatible({…}) binds any standard endpoint — Yinsi is never permanently coupled to one vendor. Providers are server-side only; keys never reach a browser or an agent's own context.

An agent names a model; the environment decides who serves it. Every provider below speaks the same OpenAI-compatible shape, so switching is configuration rather than an integration — which is the point of keeping the model layer abstract.

Selection prefers free tiers first, then local, then paid — so an operator who sets only GROQ_API_KEY gets working previews at no per-visitor cost. FINCH_PROVIDER overrides the order. The app header shows which provider is actually serving, and with none configured previews refuse rather than fabricate a response.

Model ids are env-overridable (GROQ_MODEL, OLLAMA_MODEL, …) because provider catalogs change faster than this page does — treat the defaults as a starting point, not a guarantee.

@finch/db owns operational data: agents, swarms, directory listings, execution records, per-signer spend, vector memory, the public treasury ledger, double-entry compute credits, service-call metering and hashed API keys. Unique indexes double as idempotency guarantees. Without MONGODB_URI, the site serves labeled seed data read-only; scripts: npm run seed -w @finch/db, npm run indexes -w @finch/db. MongoDB accelerates the product; Solana stays the source of truth.

Every write an agent attempts is evaluated against these rules, in this order, before anything is simulated or signed. The table is generated from POLICY_RULES in @finch/flightpath, and a test asserts that every rule the engine can actually emit appears here — so this cannot drift away from the code.

Two of these cannot be configured away. RWA interactions are always gated to the approved registry, and simulation always runs before signing — a manifest has no field that disables either.

A launched manifest does not run on Yinsi — it runs wherever you point a runtime at it. That is the whole portability claim, so here is the entrypoint, in full.

// node --experimental-strip-types run-agent.ts
import { readFileSync } from "node:fs";
import { launchFromManifest, hyperbolic } from "@finch/sdk";
import { createFlightpath } from "@finch/flightpath";

const manifest = JSON.parse(readFileSync("./market-scout.manifest.json", "utf8"));

// Observer execution layer: real Solana reads, no signer, writes denied.
// Pass operatorKey here — and only here — to grant bounded write authority.
const flightpath = createFlightpath({ agentId: manifest.identity.handle });

const agent = await launchFromManifest(manifest, {
  provider: hyperbolic(manifest.model.model),   // HYPERBOLIC_API_KEY from env
  flightpath,
});

const result = await agent.run("What is the current slot on Solana, and how busy is the network?");
console.log(result.output);
console.log(result.steps);            // every model + tool step
console.log(result.usage);            // tokens in / out
console.log(agent.unresolvedServices); // services the manifest declared but nothing resolved

Today the packages are consumed from the repo rather than from npm: clone it, or vendor packages/sdk, packages/providers and packages/flightpath into your project. They contain no TypeScript that needs compiling away — parameter properties and decorators are deliberately avoided — so node --experimental-strip-types runs them straight from source with no build step. Published npm packages are the next step, not a claim we are making now.

Triggers. A manifest can declare cron and webhook triggers, and they travel with it — but Yinsi does not schedule or receive them. Your host does: read manifest.triggers and wire them to your own scheduler or route handler. Manual is the only trigger this product acts on.

// Yinsi records triggers; your host acts on them.
for (const trigger of manifest.triggers) {
  if (trigger.kind === "cron") {
    schedule(trigger.schedule, () => agent.run("scheduled tick"));
  }
  if (trigger.kind === "webhook") {
    app.post(`/hooks/${trigger.slug}`, async (req, res) => {
      res.json(await agent.run(JSON.stringify(req.body)));
    });
  }
}

An operator can claim anything about what their agent did. An execution proof is the smallest set of facts that lets someone else check the claim: which agent acted, under which policy, in which transaction, in which slot, at what fee — plus a SHA-256 over exactly those facts, so the receipt cannot be quietly edited afterwards.

{
  "version":       "proof-of-flight/0.2",
  "finchId":       "execution-agent",       // which agent acted
  "nestId":        "my-swarm",              // set when it came from a swarm task
  "taskId":        "t4",
  "action":        "transfer.native",
  "summary":       "transfer 0.01 SOL → <recipient>",
  "chain":         "solana:mainnet",
  "signature":     "5x…",                   // the transaction, base58 — where it happened
  "slot":          "…",
  "feeLamports":   "5000",
  "computeUnits":  "150",
  "policy":        { "verdict": "allow", "rule": "default" },
  "approval":      { "approvedBy": "operator", "at": "…" },         // if a human released it
  "simulation":    { "ok": true, "computeUnits": "150" },
  "confirmedAt":   "2026-09-26T00:00:03.000Z",
  "executionHash": "9f2c…",                 // sha256 over every field above
  "explorerUrl":   "https://solscan.io/tx/5x…"   // convenience only, not hashed
}

The hash is taken over a canonical form with a fixed field order, so the same execution hashes identically on any machine in any language. Signatures are base58 and case-sensitive, so they are hashed exactly as given. Change the slot, the summary, the agent id or the approver and verifyProofOfFlight() fails.

A proof is issued only for an execution that actually confirmed. Pending, denied, reverted, or never-simulated actions throw ProofUnavailableError rather than producing a weaker receipt — that refusal is the whole point, since an execution proof means the execution happened.

import { buildProofOfFlight, verifyProofOfFlight } from "@finch/flightpath";

// record is the ExecutionRecord returned by any execution-layer write
const proof = await buildProofOfFlight(record, { nestId: "my-swarm", taskId: "t4" });

const { valid, expectedHash } = await verifyProofOfFlight(proof);
// valid === false for any edited field

Model traces and tool logs stay in the execution record offchain; only the 32-byte hash needs anchoring. The network page counts proofs by counting confirmed executions, which is exactly the set for which a proof can be issued.

Anyone can put an agent or a swarm in the directory. There is no charge and nothing to hold; the only requirement is a publisher key, and a key is issued to any Solana wallet that signs a plain message for one. The ed25519 signature proves control of the address; the address — exactly as written, since base58 is case-sensitive — becomes the key's owner; every listing published with it belongs to that wallet and can only be changed by it. One active key per wallet — signing again replaces the old one.

# 1. the wallet signs a plain message (solana:signMessage — not a transaction)
Yinsi publisher key
Address: <your base58 address>
Nonce: <random, 8-64 url-safe chars>

Signing this issues a key for publishing to the Yinsi registry. It is not a transaction.

# 2. exchange the signature for a key — shown once, only its hash is stored
POST /api/keys   { "address": "<base58 address>", "nonce": "…", "signature": "<base58, 64 bytes>" }
→ 201 { "key": "finch_…", "owner": "<the same address, exactly>", "scopes": […] }

# 3. publish with it
POST /api/directory  headers: x-finch-key: finch_…     # a directory listing
POST /api/swarms     headers: x-finch-key: finch_…     # a swarm: nest.manifest/0.1
POST /api/agents     headers: x-finch-key: finch_…     # an agent: finch.manifest/0.1

The gate is a switch, not an inference. PUBLISH_GATE unset or open is the default and the truth right now. hold turns on a token gate — a publisher must then hold at least PUBLISH_COST_FINCH of the configured token, read live at publish time — and the publish panel and GET /api/publish/status say so the moment it is on.

Published entries carry source: "published"; the network's own analysts carry source: "builtin". Either can be composed into a swarm by reference — { handle, ref: "registry" } — and is hydrated from the directory before the strict manifest schema runs.

A listing is anchored when the registry authority (FINCH_REGISTRY_AUTHORITY) has signed a memo transaction naming it: finch-registry/1 register <kind>:<handle> sha256:<manifest hash> [<uri>]. The index reads that address's signature history and counts a memo only if the authority signed it, so anyone can check a listing — and the manifest's hash — against Solana alone. Until the authority is configured, GET /api/registry reports every listing as not anchored.

Every swarm that runs teaches a shared memory, and every agent reads from it. Shared memory is not a chat log: it accepts only observations with provenance — which run, which swarm, which agent, which channel, and the address the finding is about. An agent recalling a prior finding sees it labelled exactly that way, [prior finding · my-swarm · 3h ago · unverified], so it can build on it without mistaking it for something it verified itself.

Built-in swarms write to shared memory and every swarm reads from it; none ship right now, so what it holds is what earlier runs found. The subject of a finding is the first address in the objective, so a token due-diligence run and a wallet analysis of the same mint meet in the same place. GET /api/memory shows what shared memory holds, with the provenance of every line.

No key on the server ever signs for a visitor. An agent that is allowed to write — wallet.mode: "operator" with allowances — builds the instructions with the visitor as fee payer, simulates them, then parks the intent at awaiting_signature with the exact prepared instructions. The visitor's own wallet signs and sends the transaction. Nothing on this path turns "the API returned 200" into "the transaction succeeded".

# run an agent that is allowed to write, naming the wallet that will sign
POST /api/playground/run   { "preset": "courier", "input": "send 0.01 SOL to <recipient>", "signer": "<your address>" }
→ executions: [{ id: "exec_…", state: "awaiting_signature",
                 intent: { kind: "transfer.native", summary, to, spendAsset: "native", spendAmount, meta },
                 simulation: { ok: true, computeUnits, feeLamports, simulatedAt },
                 prepared: { feePayer: "<your address>", instructions: [{ programAddress, accounts, data }], computeUnits } }]

# fetch the unsigned transaction, with a fresh blockhash
GET /api/executions/exec_…/transaction
→ { id, chain: "solana:mainnet", feePayer, transaction: "<base64 wire bytes>", lastValidBlockHeight }

# the wallet signs and sends it (solana:signAndSendTransaction); hand back the signature
POST /api/executions/exec_…/submitted   { "signature": "<base58>", "from": "<your address>" }
→ the landed transaction is compared to `prepared` instruction by instruction:
   fee payer · program · accounts and their roles · data.
   Wallet-added compute-budget and Lighthouse assertions are tolerated; any other difference is refused and nothing advances.
→ match: { id, state: "confirmed" | "reverted", tx: { signature, submittedAt },
           receipt: { status, slot, feeLamports, computeUnits, confirmedAt }, explorerUrl, proof }
   reverted = it landed with an instruction error: the fee was paid, nothing else changed
→ confirmed: an execution proof is issued

# later, exactly as stored
GET /api/executions/exec_…

States: created → simulated → awaiting_signature → submitted → confirmed | reverted, and every transition is a compare-and-set, so a double submit cannot double count. The per-transaction cap is enforced when the intent is prepared; the daily allowance is kept durably per signer, so the next intent any instance prepares for that wallet sees what it already spent today. Courier is capped at 0.1 SOL per transfer and 0.5 SOL per day. A swarm whose policy is not read-only takes the same signer on POST /api/swarms/run and surfaces its parked writes next to the task that prepared them.

Alongside plain RPC reads, agents can research. The explorer tools read Solana itself — wallet_profile, wallet_transactions, wallet_holdings, tx_lookup, token_profile, token_holders, token_activity, block_read, chain_stats — with Jupiter filling in USD prices, token records and holder counts. token_activity sees the transactions that reference a mint account; transfers that never touch it are not visible there, and the tool's description says so to the agent.

The market tools read Jupiter (token_list, token_price, and swap_quote — a route quote only, nothing is signed) and DexScreener (token_markets, market_pair). program_verified reports whether a program can still be upgraded, and by whom, and whether OtterSec has verified that its deployed build matches its source. A tool that finds nothing returns nothing; the agent is told an empty result is the answer, not a prompt to invent one.

Custody is simple and layered. Agents hold only restricted operator keypairs funded with a small float, so the most a compromised operator can lose is what it holds — and the PolicyEngine bounds every intent below that: decoded instructions, per-asset allowances and per-transaction caps, program and recipient allowlists, human approval thresholds and kill switches. Visitors sign their own transactions in their own wallets; no key on the server signs for them. The fee wallet's key is held by the operator outside the deployment — never in the repo, the deployed site, or any agent environment — and nothing moves funds automatically. The registry authority's key stays on the operator's machine, used by one script that sends nothing without --send. Production deployment is gated on the audit checklist in AUDIT.md — critical findings block release.

Protocol-level changes go through improvement proposals — one page: motivation, specification, security considerations. See the current set and the process on the research page. Code contributions follow the repository README; the audit checklist applies to anything touching signers, fees, or permissions.