nishvault-preflight-buy

v0.1.4

Published

8 days ago

Put nishvault-guard-tx before sendTransaction: x402 pre-send guard for AgentKit-style EVM agent builders on Base mainnet.

Downloads

656

Nishvault Blind-Send Risk Guard

Paid x402 preflight for one narrow buyer first: programmatic EVM agent builders.

If you arrived from x402.org, coinbase/agentkit#1167, or Merit-Systems/awesome-x402#176, the first move is the same:

npx --package nishvault-preflight-buy nishvault-guard-tx -- --seller-url https://api.nishvault.com --to 0x2222222222222222222222222222222222222222 --data 0x --value 0x0

Keep the PRE_SEND_PROOF_RECEIPT. The browser/no-wallet trust check stays at https://api.nishvault.com/first-unpaid-402?autorun=1.

Core promise:

Before your EVM agent broadcasts a transaction, run Nishvault as a paid pre-send risk guard.
put the guard directly before sendTransaction, not beside the workflow
buy one live preflight before broadcast
inspect revert risk, fee context, and likely call outcome first
do not fund a buyer wallet, sign a transaction, or pay until the unpaid 402 matches discovery

Current stage:

internal testnet rail proof is complete
live runtime target is now Base mainnet, real USDC, $0.01
settlement and wallet-credit artifacts are already proven
the next growth milestone is not “more internal proof”
the next growth milestone is one net-new outside builder reaching a mainnet unpaid 402, then one real paid request, then one fresh mainnet wallet-credit artifact

Put It In Front Of `sendTransaction`

Nishvault is not another simulator. It is the guard step before an autonomous EVM agent broadcasts.

The intended flow is now:

agent framework discovery
guard install/copy
live unpaid 402
paid preflight
external wallet-credit

Canonical first proof:

required launch gate: https://api.nishvault.com/required-before-send
proof receipt preview: https://api.nishvault.com/proof-receipt
browser-first trust step: https://api.nishvault.com/first-unpaid-402?autorun=1
first real buyer challenge: https://api.nishvault.com/first-real-buyer
root-domain trust surface: https://nishvault.com

Fastest builder interpretation:

x402.org or awesome-x402 discovery means "install/copy the guard command"
AgentKit discovery means "put nishvault-guard-tx directly before sendTransaction"
https://nishvault.com remains the trust landing and https://api.nishvault.com/first-unpaid-402 remains the no-wallet verification step

Fastest workflow entrypoints after that no-wallet proof:

`npx` one-shot guard

This is the launch gate. If an agent reaches sendTransaction, run this first and keep the PRE_SEND_PROOF_RECEIPT output.

npx --package nishvault-preflight-buy nishvault-guard-tx -- --seller-url https://api.nishvault.com --to 0x2222222222222222222222222222222222222222 --data 0x --value 0x0

Expected terminal marker:

PRE_SEND_PROOF_RECEIPT
receipt_status=...
network=eip155:8453
real_usdc=true
seller_wallet_credit_expected=true
success_signal=external_mainnet_paid_request

`viem`

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

const guardedSendTransaction = createViemPreflightGuard({
  walletClient,
  buyerKey: process.env.X402_BUYER_PRIVATE_KEY,
  sellerUrl: "https://api.nishvault.com",
});

`ethers`

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

const guardedSendTransaction = createEthersPreflightGuard({
  signer,
  buyerKey: process.env.X402_BUYER_PRIVATE_KEY,
  sellerUrl: "https://api.nishvault.com",
});

`agent step`

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

This repo is not trying to be a generic simulation dashboard. The product category for this sprint is:

Agent Transaction Safety / Pre-Send Guard

Live Surfaces

Required before-send gate: https://api.nishvault.com/required-before-send
Pre-send proof receipt: https://api.nishvault.com/proof-receipt
AgentKit patch pack: https://api.nishvault.com/agentkit-patch
ElizaOS action step: https://api.nishvault.com/elizaos-action
Public first unpaid 402 page: https://api.nishvault.com/first-unpaid-402
Public API landing: https://api.nishvault.com/
Root bridge to quickstart: https://nishvault.com/go/quickstart
Root bridge to first check: https://nishvault.com/go/first-check
Root bridge to integrations: https://nishvault.com/go/integrations
Root bridge to examples: https://nishvault.com/go/examples
Root bridge to recipes: https://nishvault.com/go/recipes
Root bridge to discovery: https://nishvault.com/go/discovery
Public quickstart: https://api.nishvault.com/quickstart
Public trust page: https://api.nishvault.com/trust
Public artifact index: https://api.nishvault.com/artifact-index
Agent-builder page: https://api.nishvault.com/agent-builders
Integrations page: https://api.nishvault.com/integrations
Example flows page: https://api.nishvault.com/examples
Recipes page: https://api.nishvault.com/recipes
How it works: https://api.nishvault.com/how-it-works
Proof page: https://api.nishvault.com/proof
Root-domain trust landing: https://nishvault.com
Discovery metadata: https://api.nishvault.com/.well-known/x402

Root-domain trust target:

live main trust surface: https://nishvault.com
live seller API surface: https://api.nishvault.com

Persona

Primary persona:

programmatic EVM agent builders

Why this buyer pays:

they already send transactions from code
they can justify paying to avoid blind-send mistakes
they are comfortable with Node, CLI, and x402-style buyer flows

Secondary fit exists for wallet teams and bots, but the copy and funnel are now optimized for the agent-builder pain first.

Why Now

Agent'in kör işlem göndermesin; yayına almadan önce tek ücretli preflight ile revert riskini gör.
Başarısız onchain denemeler yerine önce ucuz canlı preflight al.

This is positioned as a blind-send risk guard, not just a generic simulation API.

The guard rule is strict:

do not improvise a custom first flow
do not connect or fund a buyer wallet before payment_required
do not sign or broadcast anything before the unpaid 402 mirrors discovery on route, network, price, and helper links

The External Funnel

The official outside funnel is now:

agent framework discovery
guard install/copy
live unpaid 402
paid preflight
external wallet-credit

Immediate near-term milestone:

first real external unpaid 402

That is the cheapest meaningful intent signal because it does not require a funded buyer wallet yet.

One Click Or One Paste

Do not ask a first-time builder to invent a flow.

focused page: open https://api.nishvault.com/first-unpaid-402?autorun=1
browser-first: open https://nishvault.com and click Run the live unpaid 402 now
terminal-first: run one combined discovery plus unpaid command and stop at payment_required
only then decide whether the paid buyer command or transaction-flow guard is worth trying

30-Second No-Wallet Path

Do not fund or connect a buyer wallet before this unpaid proof step returns payment_required.

Hard stop before wallet connect:

expected unpaid status: 402
expected body field: error = "payment_required"
expected helper links: quickstartUrl or browserDemoUrl
stop if the route, network, or price do not match discovery
if any of the checks above fail, do not pay and do not treat the surface as trusted yet

Browser-first:

open https://api.nishvault.com/first-unpaid-402?autorun=1
confirm the response body shows error = "payment_required"

Terminal-first:

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}"
'

Expected result:

discovery returns the route and persona
unpaid POST returns payment_required

If that exact unpaid shape is missing, stop there. Do not open more docs, do not fund a wallet, and do not treat the route as trusted yet.

Fast Paid Path

First real buyer challenge:

Be the first external Base agent builder with a public pre-send proof receipt.

Open: https://api.nishvault.com/first-real-buyer

Launch-gate page: https://api.nishvault.com/required-before-send Receipt preview: https://api.nishvault.com/proof-receipt

Recommended single command after the unpaid 402 check, if you already have one transaction shape:

npx --package nishvault-preflight-buy nishvault-guard-tx -- --seller-url https://api.nishvault.com --to 0x2222222222222222222222222222222222222222 --data 0x --value 0x0

Use the generic paid buyer proof only if you are not guarding a concrete transaction yet:

npx nishvault-preflight-buy --seller-url https://api.nishvault.com --buyer-key 0xYOUR_BASE_MAINNET_BUYER_KEY --rpc-url https://mainnet.base.org --executor 0x044f05a0fcf030c53ea6d50ddc5c0a44527c1b47

After the unpaid 402, choose exactly one next move. Prefer the guard command unless you only want a generic buyer proof:

one transaction-shape guard: npx --package nishvault-preflight-buy nishvault-guard-tx -- --seller-url https://api.nishvault.com --to 0x2222222222222222222222222222222222222222 --data 0x --value 0x0
one paid buyer proof: npx nishvault-preflight-buy --seller-url https://api.nishvault.com --buyer-key 0xYOUR_BASE_MAINNET_BUYER_KEY --rpc-url https://mainnet.base.org --executor 0x044f05a0fcf030c53ea6d50ddc5c0a44527c1b47
one code-level integration path: createViemPreflightGuard, createEthersPreflightGuard, createEip1193PreflightGuard, or createAgentGuardStep

Transaction-Flow Entry

When the builder already has one transaction shape and wants Nishvault directly in the send path:

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

Publish-target equivalent:

npx --package nishvault-preflight-buy nishvault-guard-tx -- --seller-url https://api.nishvault.com --to 0x2222222222222222222222222222222222222222 --data 0x --value 0x0

Programmatic entrypoints now exported:

preflightTransactionRequest
createGuardedTransactionSender
createViemPreflightGuard
createEthersPreflightGuard
createEip1193PreflightGuard
createAgentGuardStep

Success means:

a fresh x402-paid-request-<timestamp> artifact directory exists
response status is 200
settlement includes a fresh tx hash
wallet-credit output shows mainnet_wallet_credit_seen

Mainnet Revenue Positioning

The live API is now framed as a real Base mainnet USDC product.

Correct framing:

Run one real $0.01 pre-send guard before sendTransaction.
Base mainnet USDC settlement is the revenue proof
testnet-demo remains available only as a safe dry-run profile

Public Docs

External buyer quickstart: docs/x402-external-buyer-quickstart.md
First unpaid 402 page: docs/x402-first-unpaid-402.md
Buyer trust FAQ: docs/x402-buyer-trust.md
Discoverability index: docs/x402-discoverability-index.md
Ecosystem submit pack: docs/ecosystem-submit.md
Public artifact index: docs/x402-public-artifact-index.md
Agent-builder integrations: docs/x402-agent-builder-integrations.md
Example flows: docs/x402-agent-builder-examples.md
Agent-builder recipes: docs/x402-agent-builder-recipes.md
Use-case hooks: docs/x402-use-cases.md

Proof References

Discovery artifact: research/artifacts/x402-public-origin-20260424T122405Z
Repeat-income paid request: research/artifacts/x402-paid-request-20260425T202646Z
Net-profit artifact: research/artifacts/x402-net-profit-20260425T203847Z

These prove the rail is real. They do not count as new outside customer revenue.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme