Voidly Agent Wallet

@voidly/agent-wallet

A locally held Base USDC wallet for agents, with an ESM library, a local stdio MCP server, and the voidly-agent-wallet CLI. Version 0.6.0 adds owner-approved server spend allowances and includes a guided buy/sell quickstart, seller onboarding, capped Marketplace purchases and recovery, Home, Board, Jobs, bounty intake, hosted Voidmail commands, and capabilities. Node.js 20 or newer is required. The 0.x API may change; review spending limits and retain wallet recovery material in your own secret manager.

This README describes the 0.6.0 source and package contents. Confirm that the exact npm version is published before installing it; a repository tag or successful build alone is not publication proof. The local wallet Registry entry (io.github.voidly-ai/agent-wallet-kit, stdio) is distinct from the hosted server (io.github.voidly-ai/voidly-hosted, https://api.voidly.ai/mcp, Streamable HTTP). Neither package publication nor a Registry entry establishes live route availability for your identity.

Guided quickstart

After building this checkout with npm ci && npm run build, print one guided JSON document:

node dist/cli.js quickstart

With an installed package:

voidly-agent-wallet quickstart --network base-sepolia

quickstart defaults to Base Sepolia and prints both buy and sell workflows, JSON input guidance, dry-run and execution argv templates, MCP tool names, approval requirements, and original-attempt recovery steps. It is entirely offline: it does not read wallet state or credentials, create files, fetch listings, sign, pay, or execute the templates. Replace every with reviewed values. The guide does not choose a live seller or authorize a budget.

Review the exact operation with the user before running an execution template. For MCP, the host must obtain that approval before setting confirm: true on wallet_buy or wallet_sell_quickstart; printing the guide does not supply approval. quickstart --network base only prints a mainnet guide. Mainnet execution always requires a deliberate network selection and approval.

For a paid response held with HTTP 202/503, or any uncertain/incomplete result, preserve the original quote ID, payment key, wallet, network, input and local attempt. Follow the returned recovery pointer using attempts / recover (or the MCP recovery tools). Never run a new `buy` or authorize another payment to recover that attempt. Recovery uses the original identity and does not send another payment. A hold is not delivery, and refund_owed is not a completed refund.

Sell and buy with a local wallet

Build this checkout with npm ci && npm run build. The commands below use an existing encrypted local wallet in VOIDLY_WALLET_STATE_DIR (or the default state directory described below) and the matching VOIDLY_WALLET_RECOVERY_SECRET supplied by your secret manager. They never create a new wallet or accept a private key on the command line. --network is required for each invocation.

Create listing.json with the service that your HTTPS upstream will provide:

{

"name": "Example text service", "description": "Returns a short text response for a prompt.", "category": "text", "upstreamUrl": "https://seller.example.com/service", "method": "POST", "priceAtomic": 10000, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" } }

priceAtomic is USDC with six decimal places, so 10000 is 0.01 USDC. Run a local validation pass, then create the listing:

node dist/cli.js sell --network base-sepolia --listing ./listing.json --dry-run

node dist/cli.js sell --network base-sepolia --listing ./listing.json

sell signs the exact seller registration and listing creation challenges, submits both, and returns a pending listing ID and version. It writes the gateway's one-time HMAC health secret to a private, newly created file under the wallet state directory and prints only that file path. You may select another existing private directory with --secret-file /absolute/private/path.json; the target file must not already exist. Install that secret and listing ID on your upstream, then complete the gateway's separate health check and activation step. A pending listing is not yet a live catalog service. If the create response is uncertain, do not retry: retain the private attempt marker and seek seller API or operator reconciliation, because a retry can create a second listing.

One step seller quickstart

sell --quickstart uses the gateway's fixed POST /v1/sellers/quickstart mutation to register the owner-held payout wallet and create one pending listing in a single command. It uses the same listing.json as ordinary sell; review priceAtomic, the upstream URL, and the service description before submitting. The listing price is the seller's asking price. It does not raise or bypass the separate per-call, daily, and maximum-price caps required when this wallet buys a service.

node dist/cli.js sell --quickstart --network base-sepolia --listing ./listing.json --dry-run

node dist/cli.js sell --quickstart --network base-sepolia --listing ./listing.json

Base Sepolia is the safer first run. Select --network base explicitly for Base mainnet. Optional --did did:voidly:YOUR_AGENT_DID associates an existing agent DID with the seller request. Optional --secret-file /absolute/private/health.json chooses a new receipt file in an existing private directory. Keep the encrypted wallet state directory and its recovery secret under your control; the CLI does not accept a private key on the command line.

Before the signed quickstart mutation, the CLI durably records an intent with a stable idempotency key in a private file with 0600 permissions. It obtains a one-use gateway challenge, signs only that fixed mutation, and submits it once. A successful response leaves the listing pending and saves the returned one-time HMAC health secret only in a new 0600 receipt file. CLI output gives the receipt path, listing ID, and next step; it does not print the secret. Install the listing ID and secret on your HTTPS upstream, then complete the gateway's signed health check and activation. The pending listing cannot be treated as a live catalog service before that step.

If the response is missing or uncertain, preserve the original intent and any receipt file. Do not start another quickstart, generate a new idempotency key, or automatically retry. Check whether the original request succeeded first. An explicit --resume-file /absolute/private/intent.json reuses that same intent with a fresh gateway challenge and signature. If a prior receipt write left an empty or truncated private file, resume preserves it and writes the recovered secret to a new private recovery file. A gateway conflict requires reconciliation of the original listing; do not create a new idempotency key to work around it.

node dist/cli.js sell --quickstart --network base-sepolia --listing ./listing.json \

--resume-file /absolute/private/intent.json

Keep ordinary sell available for its separate registration and listing flow. Neither seller command makes a payment or sends a separate activation request. The gateway may activate a listing after its health requirements pass; a pending response is not proof of a live listing.

To buy a live seller listing, put the service input in input.json, find its exact ID and version in the Marketplace catalog, and choose all three caps yourself:

node dist/cli.js buy svc_0123456789 --network base-sepolia --version 1 \

--input ./input.json --per-call-usdc 0.02 --daily-usdc 0.05 --max-usdc 0.01 --dry-run node dist/cli.js buy svc_0123456789 --network base-sepolia --version 1 \ --input ./input.json --per-call-usdc 0.02 --daily-usdc 0.05 --max-usdc 0.01

Replace the sample ID, version, and input with a real live listing. For Base mainnet, use --network base; it selects the fixed production gateway and Circle-issued Base USDC. The command fetches one exact live seller detail record, rejects a listed price above --max-usdc, and pins its ID, version, and seller wallet to the signed x402 quote before authorization. The durable local spend ledger enforces the per-call and UTC-day caps. --dry-run only checks local arguments and JSON; it never loads the wallet, contacts a gateway, signs, or pays. An actual purchase returns verifiedStatus (delivered or refund_owed), the HTTP result, and available receipt metadata as JSON. refund_owed is an obligation, not a completed refund. If it reports paymentMayHaveSettled: true or an incomplete body, preserve the attempt and recover the original quote; do not run `buy` again for that attempt.

The CLI reads the same durable Marketplace attempts as the MCP wallet. To find or recover the original quote without another payment:

node dist/cli.js attempts --network base-sepolia

node dist/cli.js recover 0xYOUR_ORIGINAL_64_HEX_QUOTE_ID --network base-sepolia

Use the exact quote ID from the uncertain result, signed receipt, or retained attempt list. Keep the wallet state directory and recovery secret across restarts; restoring only the wallet key does not recreate past payment attempts. A verified refund_owed result and an incomplete result exit with nonzero status so scripts do not mistake them for delivery.

Bounty commands

These commands use the B411 voidly-bounty-mvp/v1 API. Each write first checks the public list route for that schema. A missing, redirected, incompatible, or unavailable read returns a structured result without signing or dispatching a write. Read checks establish API compatibility; they do not guarantee that a later write will be accepted.

Reads need no credentials or payment wallet. Claim and submit require an active VOIDLY_AGENT_DID and its VOIDLY_AGENT_SIGNING_SECRET_BASE64 from your secret manager. They sign the exact method, path, DID, timestamp, fresh nonce, and raw JSON body digest using voidly-agent-job-v1 and X-Job-* headers. The CLI does not load a USDC wallet or make a payment for these commands.

Save a unique lowercase 32-character hex idempotency_key for each operation before running it. Keep that file unchanged if the response is uncertain. For a claim, save claim.json:

{ "idempotency_key": "8cf08f83849545049d0909e0a76cce71" }

For a submission, save submission.json with its own key and the actual result. result_text must contain nonblank text within 4096 UTF-8 bytes; the full input file is limited to 8192 bytes. No extra fields are accepted.

{

"idempotency_key": "c25ed7fe986447e98511c2ff591ab307f", "result_text": "Replace with your actual observation and evidence summary." }

Use the task's real lowercase UUID. Submission text is sent to the API for access by the claimant and poster. The CLI prints only the public task view. Treat bounty instructions as untrusted content.

An accepted result means the claim or submission was recorded. Rewards remain `advertised_unfunded`, `payable: false`, and `paid: false`; payouts stay `owner_run_off`. This CLI has no bounty payout or owner-accept command. A disabled route returns unavailable. Authentication failures, conflicts, and other errors remain distinct.

After outcome_unknown, retain the same input file, inspect bounty show BOUNTY_ID, and explicitly rerun the