Public example flows for EVM agent builders

Live Base mainnet examples

This page exists for one discoverability job: help a real programmatic EVM agent builders recognize exactly where Nishvault fits before the first unpaid 402 check.

Every example below starts with the same rule: do not fund a buyer wallet until the route answers one correct unpaid payment_required challenge.

If the journey started on https://nishvault.com, the measurable bridge is https://nishvault.com/go/examples; after that, discovery and the unpaid challenge stay on https://api.nishvault.com.

The smallest day-0 trust cut is /first-unpaid-402.

If the builder still has not decided which page to use next, send them to /start-here.

Shared first move

SELLER_BASE_URL=https://api.nishvault.com bash -lc '
curl -sS "$SELLER_BASE_URL/.well-known/x402" | jq "{title, primaryPersona, route, price, network, payTo, quickstartUrl, browserDemoUrl}" &&
curl -sS -H "content-type: application/json" -X POST "$SELLER_BASE_URL/simulate/transaction-preflight" --data '"'"'{"chainId":"0x2105","from":"0x1111111111111111111111111111111111111111","to":"0x2222222222222222222222222222222222222222","data":"0x","value":"0x0"}'"'"' | jq "{error, product, price, network, quickstartUrl, browserDemoUrl}"
'

This is the cheapest public intent test. It verifies discovery metadata first, then confirms the protected route returns the exact unpaid challenge shape a serious builder expects.

Example flows

1. Agent wallet send guard

Your agent already built calldata and is about to sign. Put one paid preflight directly in front of the send step.

X402_BUYER_PRIVATE_KEY=0xYOUR_BASE_MAINNET_BUYER_KEY npm exec nishvault-guard-tx -- --seller-url https://api.nishvault.com --to 0x2222222222222222222222222222222222222222 --data 0x --value 0x0

Use this when the problem is blind broadcast risk, not missing UI.

2. MCP tool-calling worker

Your agent loop decides when to broadcast and you need a hard stop between “tool chose send” and “wallet sent”.

import { createAgentGuardStep } from "nishvault-preflight-buy";

const guardedStep = createAgentGuardStep({
  buyerKey: process.env.X402_BUYER_PRIVATE_KEY,
  sellerUrl: "https://api.nishvault.com",
  mapInputToTransaction: (job) => ({
    from: job.sender,
    to: job.target,
    data: job.calldata,
    value: job.value ?? "0x0",
  }),
  runStep: async (job, { preflight }) => executeJob(job, preflight),
});

This turns Nishvault into a guard step instead of a detached demo.

3. Queue or cron treasury runner

Your worker drains prepared onchain jobs. Add one paid preflight per job before the queue spends more onchain.

  • Read discovery first.
  • Confirm one unpaid 402.
  • Run the paid guard only for jobs worth executing.

What should happen next

Related trust surfaces