Hoshi

Financial operating system for AI agents and internet businesses on Solana.

Hoshi is a modular TypeScript monorepo: a core SDK for treasury-style operations (wallets, transfers, invoices, swaps, yield), a policy engine for rule-gated actions, an HTTP gateway with x402-style metering for paid API proxying, an MCP server so agents can call financial tools over the Model Context Protocol, and a developer CLI for local workflows.

Requirements

Tool	Version
Node.js	20.x LTS or newer recommended
pnpm	9.x (workspace pins `packageManager` in root `package.json`)

Quick start

git clone <repository-url>
cd <repo-root>   # workspace root: contains `pnpm-workspace.yaml`
pnpm install
pnpm build
pnpm test

pnpm build — builds all packages via Turborepo (dist/ in each package).
pnpm test — runs package test suites (Vitest).
pnpm dev — watch mode for packages that define a dev script (typically tsup --watch).

Repository layout

Package	NPM name	Role
SDK	`@hoshi/sdk`	Solana-facing primitives: chain adapter, wallets, transfers, invoices, swaps (Jupiter), yield (Kamino), receipts
Engine	`@hoshi/engine`	Policy evaluation and orchestration on top of SDK types
Gateway	`@hoshi/gateway`	Hono HTTP app: health, service catalog, stats, x402-guarded `/proxy/...`
MCP	`@hoshi/mcp`	Stdio MCP server exposing financial tools to AI clients
CLI	`@hoshi/cli`	`hoshi` binary: wallets, transfers, swap quotes, policy CRUD

All packages are workspace-linked; the root workspace lists @hoshi/cli as a devDependency so pnpm exec hoshi works from the repo root after pnpm install.

Running the stack

CLI (`hoshi`)

From the repository root (after pnpm build):

pnpm exec hoshi --help

Common global options:

--rpc <url> — Solana RPC (default: devnet).
--mainnet — use public mainnet-beta RPC.
-k, --keypair <path> — keypair JSON for signing (required for send flows).

Local state is written under ~/.hoshi/ (store.json, policies.json), not inside the repo.

HTTP Gateway

Runs a standalone Node server (default port 3000).

pnpm build
node packages/hoshi-gateway/dist/server.js

Optional: PORT — listen port (default 3000).

Method	Path	Purpose
`GET`	`/health`	Liveness / version
`GET`	`/services`	List registered upstream services
`GET`	`/services/:id`	Service detail
`GET`	`/stats`	Metering stats
`ALL`	`/proxy/:serviceId/*`	Paid proxy (x402 middleware + metering)

The shipped server registers sample upstream definitions (e.g. OpenAI, Anthropic shapes) for demonstration; replace or extend the registry for real deployments.

MCP server (`hoshi-mcp`)

The server speaks newline-delimited JSON-RPC on stdin/stdout (standard MCP over stdio).

pnpm build
pnpm --filter @hoshi/mcp exec hoshi-mcp

Wire this command into your MCP client (see below). Default Solana RPC in code is devnet; adjust in source or future configuration as you harden for production.

MCP integration

Tools registered by the server (names are stable identifiers for tools/call):

Tool	Purpose
`hoshi_balance`	Wallet / balance read
`hoshi_send`	Transfer execution
`hoshi_create_invoice`	Create invoice
`hoshi_create_payment_link`	Payment link
`hoshi_swap_quote`	Swap quote (Jupiter)
`hoshi_deposit_yield`	Yield deposit flow
`hoshi_history`	History / activity

Example (Cursor / Claude Desktop-style config): add a server entry whose command runs Node on the built binary, from your machine’s absolute paths:

{
  "mcpServers": {
    "hoshi": {
      "command": "node",
      "args": ["/absolute/path/to/Hoshi/packages/hoshi-mcp/dist/server.js"]
    }
  }
}

Alternatively use pnpm --filter @hoshi/mcp exec hoshi-mcp as command with cwd set to the repo root if your client supports it.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Host apps (e.g. Kitsu) — not in this repo                  │
├─────────────────────────────────────────────────────────────┤
│  @hoshi/gateway          │  @hoshi/mcp                      │
│  HTTP + x402 metering    │  MCP (stdio)                     │
├─────────────────────────────────────────────────────────────┤
│  @hoshi/engine — policies, approvals, execution rules       │
├─────────────────────────────────────────────────────────────┤
│  @hoshi/sdk — Solana + DeFi adapters, treasury primitives   │
└─────────────────────────────────────────────────────────────┘

Data flow summary:

SDK encapsulates chain and protocol adapters and returns structured results/receipts.
Engine evaluates policy before or alongside sensitive operations (used by CLI; extend as needed for gateway/MCP).
Gateway exposes metered, paid access to configured HTTP upstreams.
MCP exposes the same financial surface to LLM agents via tools.

Design principles

Stablecoin-first — treasury and payments semantics (e.g. USDC), not speculative trading as a product goal.
Policy-bound autonomy — autonomous agents should run under explicit rules (limits, allowlists, approval patterns).
Receipts and auditability — operations should yield consistent, machine-readable outcomes for logging and reconciliation.
Composable packages — consume Hoshi as libraries, gateway, or MCP without coupling to a specific consumer app.

Development

pnpm dev           # watch builds (tsup --watch) where defined
pnpm typecheck     # `tsc --noEmit` in packages that define the script
pnpm clean         # turbo clean — removes `dist/` (and similar) per package

pnpm lint is wired at the root through Turborepo; individual packages do not define lint tasks yet, so it is currently a no-op.

Single-package focus:

pnpm --filter @hoshi/sdk test
pnpm --filter @hoshi/gateway build

Production notes

This repository is an MVP-grade foundation. Before you rely on it in production, run pnpm build and pnpm test on the exact commit you intend to ship, and treat deployment as requiring your own checklist:

RPC — use private, rate-limited endpoints for production; defaults are public devnet/mainnet URLs where applicable.
Keys — never commit keypairs; CLI uses local filesystem paths only.
Gateway — replace in-memory registry/metering with persistent stores and real x402/settlement integration as needed.
MCP — stdio servers must be spawned by a trusted host; scope tool access and RPC the same way you would any custodial or signing-capable integration.
Compliance — treasury, invoicing, and money transmission rules depend on your jurisdiction and use case; this codebase is not legal or compliance advice.

For security-sensitive issues, follow your organization’s disclosure process; there is no separate SECURITY.md in-tree yet.

License

MIT

Name		Name	Last commit message	Last commit date
.anchor/test-ledger		.anchor/test-ledger
.github/workflows		.github/workflows
apps/landing		apps/landing
packages		packages
programs/hoshi-kya		programs/hoshi-kya
runbooks		runbooks
scripts		scripts
tests		tests
.gitignore		.gitignore
Anchor.toml		Anchor.toml
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json
txtx.yml		txtx.yml

Navigation Menu

Repository files navigation

Hoshi

Contents

Requirements

Quick start

Repository layout

Running the stack

CLI (`hoshi`)

HTTP Gateway

MCP server (`hoshi-mcp`)

MCP integration

Architecture

Design principles

Development

Production notes

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Hoshi

Contents

Requirements

Quick start

Repository layout

Running the stack

CLI (hoshi)

HTTP Gateway

MCP server (hoshi-mcp)

MCP integration

Architecture

Design principles

Development

Production notes

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

CLI (`hoshi`)

MCP server (`hoshi-mcp`)