CLI Reference - Sinker

Overview

sinker is a single binary that starts the transaction sidecar and provides developer commands for inspecting its live state. No separate installation required — build once, use everywhere.

cd sinker
cargo build --release
./target/release/sinker --help

Sidecar commands

`sinker up`

Start the full stack — sidecar and AI agent together in a single terminal. Both processes share stdout, with agent lines prefixed by [ AGENT ] so the streams stay readable.

sinker up

Use this for normal development and production. Use sinker start only when you need the sidecar without the agent (e.g. bypass mode, debugging the sidecar in isolation).

`sinker start`

Start the sidecar in agent mode. The AI agent reads the live tip oracle, decides the optimal tip, and submits your queued transactions as Jito bundles.

sinker start

`sinker start --bypass`

Bypass the AI agent and submit transactions at a fixed tip (default: 10,000 lamports). Useful for testing the frontend → sidecar → Jito path without waiting for the agent.

sinker start --bypass
sinker start --bypass --tip 50000

Flag	Description
`--bypass`	Skip the AI agent, submit immediately on each `tx_enqueued` event
`--tip <lamports>`	Fixed tip amount in lamports (default: `10000`). Only used with `--bypass`.

`sinker agent`

Start the TypeScript AI agent in a separate process. Runs npm run dev inside the agents/ directory (override with AGENT_DIR env var).

sinker agent

`sinker web`

Start the Next.js web frontend. Runs npm run dev inside the web/ directory (override with WEB_DIR env var).

sinker web

`sinker smoke`

Run the stream_smoke integration test — connects to Yellowstone, waits for a Jito leader window, submits one bundle, and polls until finalization.

sinker smoke

Inspect commands

Inspect commands query a running sidecar at http://localhost:{API_PORT} (default 7777). Start the sidecar first with sinker start.

`sinker status`

Print a summary of the current sidecar state: slot, leader identity, tip floor (p50/p75), and pending queue depth.

$ sinker status
┌─ Sidecar Status ─────────────────────────────────
│  slot     : 318456201
│  leader   : 9xRc...
│  tip p50  : 9850 lamports
│  tip p75  : 14200 lamports
│  stale    : false
│  queue    : 0 pending tx(s)
└──────────────────────────────────────────────────

`sinker tip`

Print the full tip floor percentile table.

$ sinker tip
┌─ Tip Floor Percentiles ──────────────────────────
│  p25  :       6500 lamports
│  p50  :       9850 lamports
│  p75  :      14200 lamports
│  p95  :      31000 lamports
│  p99  :      75000 lamports
│  ema  :       9200 lamports
│  stale: false
└──────────────────────────────────────────────────

`sinker queue`

Print the pending transaction queue contents with age and priority.

$ sinker queue
pending: 2  (evicted_total: 0)
  tx_id=3fa2...  age=3slots  priority=normal
  tx_id=7b1c...  age=1slots  priority=high

`sinker lifecycle`

Print recent bundle lifecycle history. Shows the most recent 10 entries by default.

sinker lifecycle
sinker lifecycle --last 25

showing 3/3 entries (most recent last):
bundle_id             stage       slot          failure     tip
──────────────────────────────────────────────────────────────────────
8f3a1b2c4d5e6f70      finalized   318456120     —           9850L
2e7d4c3b1a0f9e8d      failed      318456185     fee_too_low  8000L
5c9a2f1e8b4d3c70      finalized   318456198     —           14200L

Flag	Description
`--last N` / `-l N`	Number of entries to show (default: 10)

`sinker bundle <id>`

Print the full JSON lifecycle entry for a specific bundle.

sinker bundle 8f3a1b2c4d5e6f70abcdef1234567890abcdef12

{
  "bundle_id": "8f3a1b2c4d5e6f70...",
  "stage": "finalized",
  "slot_submitted": 318456120,
  "tip_lamports": 9850,
  "submitted_at": "2025-06-01T12:34:56.789Z",
  "finalized_at": "2025-06-01T12:35:02.123Z",
  "transactions": ["5xKp..."],
  ...
}

Policy commands

sinker policy gates what the AI agent is allowed to do — tip caps, retry limits, queue depth, and throughput controls. Settings persist in sinker.policy.json between restarts.

sinker policy show                        # print all values and override status
sinker policy set max-tip 200000          # hard ceiling on tip size
sinker policy set tip-percentile p95      # target a higher percentile
sinker policy validate                    # check for contradictions
sinker policy clear                       # delete file, revert all to defaults

Policy reference →

Full reference for all 10 policy keys and 7 sub-commands.

Environment variables

Variable	Default	Description
`YELLOWSTONE_ENDPOINT`	required	Yellowstone gRPC endpoint
`YELLOWSTONE_X_TOKEN`	—	Yellowstone auth token (if required)
`RPC_URL`	required	Solana RPC URL (mainnet Helius recommended)
`JITO_BLOCK_ENGINE_URL`	`mainnet.block-engine.jito.wtf`	Jito block engine
`JITO_UUID`	—	Jito auth UUID for higher rate limits
`KEYPAIR_PATH`	`~/.config/solana/id.json`	Path to signing keypair
`API_PORT`	`7777`	Sidecar API port
`BYPASS_AGENT`	`0`	Set `1` to enable bypass mode via env
`BYPASS_TIP_LAMPORTS`	`10000`	Fixed tip for bypass mode (lamports)
`AGENT_DIR`	`../agents`	Directory for `sinker agent`
`WEB_DIR`	`../web`	Directory for `sinker web`
`SINKER_POLICY_FILE`	`./sinker.policy.json`	Custom path for the policy file

​Overview

​Sidecar commands

​sinker up

​sinker start

​sinker start --bypass

​sinker agent

​sinker web

​sinker smoke

​Inspect commands

​sinker status

​sinker tip

​sinker queue

​sinker lifecycle

​sinker bundle <id>

​Policy commands