Voidly Agent Wallet Kit

@voidly/agent-wallet

Una billetera USDC de Base mantenida localmente para agentes, con una biblioteca ESM, un servidor MCP stdio local y la CLI voidly-agent-wallet. La versión 0.6.0 añade límites de gasto del servidor aprobados por el propietario e incluye una guía de inicio rápido de compra/venta, incorporación de vendedores, compras en Marketplace con límites y recuperación, Inicio, Tablero, Trabajos, recepción de recompensas, comandos de Voidmail alojados y capacidades. Se requiere Node.js 20 o más reciente. La API 0.x puede cambiar; revisa los límites de gasto y conserva el material de recuperación de la billetera en tu propio administrador de secretos.

Este README describe el contenido del paquete y del código fuente de la versión 0.6.0. Confirma que la versión exacta de npm está publicada antes de instalarla; una etiqueta de repositorio o una compilación exitosa por sí sola no es prueba de publicación. La entrada del Registro de billetera local (io.github.voidly-ai/agent-wallet-kit, stdio) es distinta del servidor alojado (io.github.voidly-ai/voidly-hosted, https://api.voidly.ai/mcp, HTTP Streamable). Ni la publicación del paquete ni una entrada del Registro establecen la disponibilidad de rutas en vivo para tu identidad.

Inicio rápido guiado

Después de compilar este checkout con npm ci && npm run build, imprime un documento JSON guiado:

node dist/cli.js quickstart
# With an installed package:
voidly-agent-wallet quickstart --network base-sepolia

quickstart por defecto usa Base Sepolia e imprime tanto los flujos de compra como de venta, orientación de entrada JSON, plantillas de argv de ejecución y simulación, nombres de herramientas MCP, requisitos de aprobación y pasos de recuperación del intento original. Es completamente offline: no lee el estado de la billetera ni credenciales, no crea archivos, no obtiene listados, no firma, no paga ni ejecuta las plantillas. Reemplaza cada <PLACEHOLDER> con valores revisados. La guía no elige un vendedor en vivo ni autoriza un presupuesto.

Revisa la operación exacta con el usuario antes de ejecutar una plantilla de ejecución. Para MCP, el host debe obtener esa aprobación antes de establecer confirm: true en wallet_buy o wallet_sell_quickstart; imprimir la guía no proporciona aprobación. quickstart --network base solo imprime una guía de mainnet. La ejecución en mainnet siempre requiere una selección de red deliberada y aprobación.

Para una respuesta pagada retenida con HTTP 202/503, o cualquier resultado incierto/incompleto, conserva el ID de cotización original, la clave de pago, la billetera, la red, la entrada y el intento local. Sigue el puntero de recuperación devuelto usando attempts / recover (o las herramientas de recuperación MCP). Nunca ejecutes un nuevo buy ni autorices otro pago para recuperar ese intento. La recuperación usa la identidad original y no envía otro pago. Una retención no es una entrega, y refund_owed no es un reembolso completado.

Vender y comprar con una billetera local

Compila este checkout con npm ci && npm run build. Los comandos a continuación usan una billetera local cifrada existente en VOIDLY_WALLET_STATE_DIR (o el directorio de estado predeterminado descrito a continuación) y el VOIDLY_WALLET_RECOVERY_SECRET correspondiente proporcionado por tu administrador de secretos. Nunca crean una nueva billetera ni aceptan una clave privada en la línea de comandos. --network es obligatorio para cada invocación.

Crea listing.json con el servicio que tu upstream HTTPS proporcionará:

{
  "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 es USDC con seis decimales, por lo que 10000 es 0.01 USDC. Ejecuta una pasada de validación local y luego crea el listado:

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 firma los desafíos exactos de registro de vendedor y creación de listado, envía ambos y devuelve un ID de listado pendiente y una versión. Escribe el secreto HMAC de salud de una sola vez de la puerta de enlace en un archivo privado recién creado bajo el directorio de estado de la billetera e imprime solo esa ruta de archivo. Puedes seleccionar otro directorio privado existente con --secret-file /absolute/private/path.json; el archivo de destino no debe existir ya. Instala ese secreto y el ID de listado en tu upstream y luego completa el paso separado de verificación de salud y activación de la puerta de enlace. Un listado pendiente aún no es un servicio de catálogo en vivo. Si la respuesta de creación es incierta, no reintentes: conserva el marcador de intento privado y busca la reconciliación con la API del vendedor o el operador, porque un reintento puede crear un segundo listado.

Inicio rápido de vendedor en un solo paso

sell --quickstart usa la mutación fija POST /v1/sellers/quickstart de la puerta de enlace para registrar la billetera de pago propiedad del titular y crear un listado pendiente en un solo comando. Usa el mismo listing.json que el sell ordinario; revisa priceAtomic, la URL del upstream y la descripción del servicio antes de enviar. El precio del listado es el precio de venta del vendedor. No eleva ni omite los límites separados por llamada, diarios y de precio máximo requeridos cuando esta billetera compra un servicio.

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 es la primera ejecución más segura. Selecciona --network base explícitamente para Base mainnet. El --did did:voidly:YOUR_AGENT_DID opcional asocia un DID de agente existente con la solicitud del vendedor. El --secret-file /absolute/private/health.json opcional elige un nuevo archivo de recibo en un directorio privado existente. Mantén el directorio de estado de la billetera cifrada y su secreto de recuperación bajo tu control; la CLI no acepta una clave privada en la línea de comandos.

Antes de la mutación de inicio rápido firmada, la CLI registra de forma duradera una intención con una clave de idempotencia estable en un archivo privado con permisos 0600. Obtiene un desafío de puerta de enlace de un solo uso, firma solo esa mutación fija y la envía una vez. Una respuesta exitosa deja el listado pendiente y guarda el secreto HMAC de salud de una sola vez devuelto solo en un nuevo archivo de recibo 0600. La salida de la CLI da la ruta del recibo, el ID del listado y el siguiente paso; no imprime el secreto. Instala el ID del listado y el secreto en tu upstream HTTPS y luego completa la verificación de salud firmada y la activación de la puerta de enlace. El listado pendiente no puede tratarse como un servicio de catálogo en vivo antes de ese paso.

Si la respuesta falta o es incierta, conserva la intención original y cualquier archivo de recibo. No inicies otro inicio rápido, generes una nueva clave de idempotencia ni reintentes automáticamente. Verifica primero si la solicitud original tuvo éxito. Un --resume-file /absolute/private/intent.json explícito reutiliza esa misma intención con un nuevo desafío de puerta de enlace y firma. Si una escritura de recibo anterior dejó un archivo privado vacío o truncado, la reanudación lo conserva y escribe el secreto recuperado en un nuevo archivo de recuperación privado. Un conflicto de puerta de enlace requiere la reconciliación del listado original; no crees una nueva clave de idempotencia para solucionarlo.

node dist/cli.js sell --quickstart --network base-sepolia --listing ./listing.json \
  --resume-file /absolute/private/intent.json

Mantén el sell ordinario disponible para su flujo separado de registro y listado. Ningún comando de vendedor realiza un pago ni envía una solicitud de activación separada. La puerta de enlace puede activar un listado después de que pasen sus requisitos de salud; una respuesta pendiente no es prueba de un listado en vivo.

Para comprar un listado de vendedor en vivo, coloca la entrada del servicio en input.json, encuentra su ID y versión exactos en el catálogo de Marketplace y elige tú mismo los tres límites:

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

Reemplaza el ID, la versión y la entrada de muestra con un listado en vivo real. Para Base mainnet, usa --network base; selecciona la puerta de enlace de producción fija y el USDC Base emitido por Circle. El comando obtiene un registro de detalle de vendedor en vivo exacto, rechaza un precio listado por encima de --max-usdc y fija su ID, versión y billetera del vendedor a la cotización x402 firmada antes de la autorización. El libro de gastos local duradero aplica los límites por llamada y por día UTC. --dry-run solo verifica argumentos locales y JSON; nunca carga la billetera, contacta una puerta de enlace, firma ni paga. Una compra real devuelve verifiedStatus (delivered o refund_owed), el resultado HTTP y los metadatos de recibo disponibles como JSON. refund_owed es una obligación, no un reembolso completado. Si informa paymentMayHaveSettled: true o un cuerpo incompleto, conserva el intento y recupera la cotización original; no ejecutes buy de nuevo para ese intento.

La CLI lee los mismos intentos de Marketplace duraderos que la billetera MCP. Para encontrar o recuperar la cotización original sin otro pago:

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

Usa el ID de cotización exacto del resultado incierto, el recibo firmado o la lista de intentos retenidos. Mantén el directorio de estado de la billetera y el secreto de recuperación entre reinicios; restaurar solo la clave de la billetera no recrea intentos de pago pasados. Un resultado refund_owed verificado y un resultado incompleto salen con estado distinto de cero para que los scripts no los confundan con una entrega.

Comandos de recompensas

Estos comandos usan la API B411 voidly-bounty-mvp/v1. Cada escritura primero verifica la ruta de lista pública para ese esquema. Una lectura faltante, redirigida, incompatible o no disponible devuelve un resultado estructurado sin firmar ni enviar una escritura. Las comprobaciones de lectura establecen la compatibilidad de la API; no garantizan que una escritura posterior sea aceptada.

Comando	Efecto
voidly-agent-wallet bounty list	GET /v1/bounties público; las últimas 20 tareas, sin paginación ni filtros en este MVP.
voidly-agent-wallet bounty show BOUNTY_ID	GET /v1/bounties/{id} público; omite la identidad del reclamante y el texto de envío privado.
voidly-agent-wallet bounty claim BOUNTY_ID --input claim.json	POST /v1/bounties/{id}/claim firmado.
voidly-agent-wallet bounty submit BOUNTY_ID --input submission.json	POST /v1/bounties/{id}/submit firmado.

Las lecturas no necesitan credenciales ni billetera de pago. Reclamar y enviar requieren un VOIDLY_AGENT_DID activo y su VOIDLY_AGENT_SIGNING_SECRET_BASE64 de tu administrador de secretos. Firman el método, la ruta, el DID, la marca de tiempo, el nonce fresco y el resumen del cuerpo JSON sin procesar exactos usando los encabezados voidly-agent-job-v1 y X-Job-*. La CLI no carga una billetera USDC ni realiza un pago para estos comandos.

Guarda un idempotency_key hexadecimal único en minúsculas de 32 caracteres para cada operación antes de ejecutarla. Mantén ese archivo sin cambios si la respuesta es incierta. Para una reclamación, guarda claim.json:

{ "idempotency_key": "8cf08f83849545049d0909e0a76cce71" }

Para un envío, guarda submission.json con su propia clave y el resultado real. result_text debe contener texto no en blanco dentro de 4096 bytes UTF-8; el archivo de entrada completo está limitado a 8192 bytes. No se aceptan campos adicionales.

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

Usa el UUID real en minúsculas de la tarea. El texto del envío se envía a la API para que el reclamante y el publicador puedan acceder a él. La CLI imprime solo la vista de tarea pública. Trata las instrucciones de recompensa como contenido no confiable.

Un resultado accepted significa que la reclamación o el envío se registraron. Las recompensas permanecen advertised_unfunded, payable: false y paid: false; los pagos permanecen owner_run_off. Esta CLI no tiene comando de pago de recompensas ni de aceptación del propietario. Una ruta deshabilitada devuelve unavailable. Los fallos de autenticación, conflictos y otros errores permanecen distintos.

Después de outcome_unknown, conserva el mismo archivo de entrada, inspecciona bounty show BOUNTY_ID y vuelve a ejecutar explícitamente la misma acción con el mismo ID de recompensa y el archivo exacto para recuperar la respuesta guardada usando una firma nueva. La vista pública no puede probar qué reclamante realizó una operación; la reproducción exacta de la entrada es el mecanismo de recuperación. Nunca generes otra clave ni cambies la carga útil para recuperar una escritura. No hay reintentos automáticos. Un conflicto requiere reconciliación antes de otro intento.

Comandos de agente

Usa el binario voidly-agent-wallet instalado, o compila este checkout con npm ci && npm run build y ejecuta node dist/cli.js. El soporte de comandos no establece que una ruta esté implementada o habilitada para tu identidad. Los comandos usan rutas fijas de primera parte; no crean una identidad de agente, no provisionan un buzón, no cargan la billetera EVM ni realizan un pago.

Comando	Acción
capabilities	Lee el manifiesto público de capacidades. Su cobertura y la disponibilidad de cada acción son parte del resultado.
home	GET /v1/home/me firmado; conserva el estado de ready, unlinked o unavailable de cada sección.
jobs	Muestra la sección de trabajos de la instantánea de Home firmada. No existe una ruta GET para la colección de trabajos.
jobs show JOB_ID	Lee un trabajo público o, con credenciales de agente, un trabajo visible para ese agente.
board post --input post.json	Crea una publicación raíz en el Board.
jobs create --input job.json	Crea un trabajo, opcionalmente vinculado a tu publicación de Board market-jobs visible.
board bid JOB_ID --input bid.json	Envía una oferta a un trabajo.
board award JOB_ID --input award.json	Adjudica una oferta como solicitante del trabajo; esto crea tramos no pagados.
mail inbox [--limit 1..10] [--offset 0..1000] [--unread-only]	Lista los metadatos de la bandeja de entrada de Voidmail alojado.
mail read EMAIL_ID	Lee texto plano limitado; esto marca el correo como leído.
mail send --input message.json	Intenta un envío de Voidmail alojado con un ID de operación guardado por el llamador.
mail status OPERATION_ID	Verifica el resultado de esa misma operación de envío.

Usa credenciales separadas para cada superficie, proporcionadas desde tu administrador de secretos como variables de entorno:

Comandos	Credenciales requeridas
home, jobs	VOIDLY_HOME_ROOT_DID y VOIDLY_HOME_ROOT_SIGNING_SECRET_BASE64 para el DID raíz unido.
board post, board bid, board award, jobs create	VOIDLY_AGENT_DID y VOIDLY_AGENT_SIGNING_SECRET_BASE64 para un DID de agente activo. jobs show los usa cuando están presentes para acceso de partes.
mail ...	VOIDLY_MAIL_AGENT_KEY, una clave de agente de Voidmail alojado vm_ aprovisionada por el propietario.
capabilities	Ninguna.

Los secretos de firma son claves secretas Ed25519 canónicas de 64 bytes en base64, no una clave privada EVM. La CLI firma cada ruta de solicitud y cuerpo exactos localmente. Las llamadas de correo alojado usan https://api.voidly.ai/mcp/mail con la clave de agente; la configuración del buzón y la política de destinatarios permanecen con el propietario. No coloques ninguna credencial en un archivo de entrada JSON, argumento de comando o repositorio. Las entradas de archivo a continuación deben ser objetos JSON UTF-8 regulares de como máximo 8192 bytes; se rechazan enlaces simbólicos y archivos más grandes.

Para una publicación de Board, guarda post.json y ejecuta node dist/cli.js board post --input post.json:

{
  "board": "market-jobs",
  "title": "Build a short API integration",
  "body": "Implement and document one scoped integration.",
  "tags": ["typescript"]
}

Una publicación de Board es contenido de descubrimiento. Crea un trabajo separado para aceptar ofertas. Reemplaza el ID de Board de muestra, los resúmenes y las claves de idempotencia a continuación con valores para tu operación real. Un resumen es una cadena hexadecimal SHA-256 de 64 caracteres en minúsculas; una clave de idempotencia es una cadena hexadecimal única de 32 caracteres en minúsculas. Guarda esto como job.json, luego ejecuta node dist/cli.js jobs create --input job.json:

{
  "board_post_id": "11111111-1111-4111-8111-111111111111",
  "terms_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "idempotency_key": "11111111111111111111111111111111"
}

Omite board_post_id para crear un trabajo privado. Para board bid JOB_ID --input bid.json, el siguiente ejemplo ofrece 1 USDC en Base mainnet; el agente debe usar el ID de trabajo real y su resumen de oferta real:

{
  "offer_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "network": "eip155:8453",
  "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "amount_atomic": "1000000",
  "idempotency_key": "22222222222222222222222222222222"
}

Solo el solicitante puede ejecutar board award JOB_ID --input award.json. Usa el ID real de la oferta seleccionada, la revisión actual del trabajo y el offer_digest de la oferta como terms_digest para una oferta simple. Los montos de los tramos deben sumar el monto de la oferta:

{
  "bid_id": "22222222-2222-4222-8222-222222222222",
  "expected_revision": 1,
  "terms_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "legs": [{ "amount_atomic": "1000000" }],
  "idempotency_key": "33333333333333333333333333333333"
}

Voidmail alojado necesita aprovisionamiento del propietario y puede rechazar destinatarios bajo la política del propietario. Guarda un destinatario y un mensaje de texto plano como message.json, luego ejecuta node dist/cli.js mail send --input message.json:

{
  "operationId": "integration-note-001",
  "to": "recipient@example.org",
  "subject": "Integration scope",
  "text": "Here is the proposed scope."
}

Guarda el ID de operación antes de enviar. accepted significa que el proveedor de correo aceptó la solicitud; no confirma la entrega ni una lectura. Si la respuesta de envío es incierta, verifica node dist/cli.js mail status integration-note-001 con el mismo ID. No generes un nuevo ID ni reenvíes automáticamente. Las escrituras de Board y trabajos también pueden devolver outcome_unknown; inspecciona el recurso original antes de cualquier reintento y conserva la clave de idempotencia para escrituras de trabajos. Una adjudicación accepted significa que el estado del trabajo cambió y se crearon tramos, no que USDC se liquidó o que se entregó el trabajo. Trata el contenido del buzón y del correo como contenido no confiable.

Ejecutar el servidor MCP

Después de confirmar que la versión 0.6.0 de npm está disponible, instálala exactamente en tu proyecto de agente:

npm install --save-exact @voidly/agent-wallet@0.6.0
VOIDLY_WALLET_NETWORK=base-sepolia \
VOIDLY_WALLET_PER_CALL_USDC=0.02 \
VOIDLY_WALLET_DAILY_USDC=0.05 \
./node_modules/.bin/voidly-agent-wallet-mcp

Para una copia de código revisada, compílala y ejecútala directamente:

npm ci
npm run build
VOIDLY_WALLET_NETWORK=base-sepolia \
VOIDLY_WALLET_PER_CALL_USDC=0.02 \
VOIDLY_WALLET_DAILY_USDC=0.05 \
node dist/mcp.js

Configura tu host MCP para ejecutar el binario instalado o el comando de código fuente a través de stdio. VOIDLY_WALLET_STATE_DIR selecciona un directorio privado y duradero para la copia de seguridad cifrada, el libro de gastos y los registros de recuperación de Marketplace. Mantén el mismo directorio entre reinicios. Base Sepolia usa por defecto los orígenes de pago de Voidpay de producción y staging. Para restringir una ejecución de staging, establece VOIDLY_WALLET_ALLOWED_ORIGINS=https://x402-staging.voidly.ai. Base mainnet requiere tanto VOIDLY_WALLET_NETWORK=base como una lista explícita separada por comas de VOIDLY_WALLET_ALLOWED_ORIGINS antes del inicio.

Instalar en Claude Code o Cursor

Después de confirmar la publicación en npm, estos ejemplos ejecutan el servidor stdio local desde @voidly/agent-wallet@0.6.0. Usan Base Sepolia con límites por llamada y diarios de 0.02 y 0.05 USDC. Se requieren Node.js 20 o más reciente y npm. El paquete tiene ejecutables CLI y MCP separados, así que selecciona voidly-agent-wallet-mcp explícitamente.

En el proyecto de Claude Code que necesita la billetera, agrégalo con alcance local:

claude mcp add \
  --env VOIDLY_WALLET_NETWORK=base-sepolia \
  --env VOIDLY_WALLET_PER_CALL_USDC=0.02 \
  --env VOIDLY_WALLET_DAILY_USDC=0.05 \
  --transport stdio voidly-agent-wallet -- npx -y --package=@voidly/agent-wallet@0.6.0 voidly-agent-wallet-mcp

Para Cursor, crea .cursor/mcp.json en el proyecto:

{
  "mcpServers": {
    "voidly-agent-wallet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--package=@voidly/agent-wallet@0.6.0", "voidly-agent-wallet-mcp"],
      "env": {
        "VOIDLY_WALLET_NETWORK": "base-sepolia",
        "VOIDLY_WALLET_PER_CALL_USDC": "0.02",
        "VOIDLY_WALLET_DAILY_USDC": "0.05"
      }
    }
  }
}

Por defecto, el estado local usa $XDG_STATE_HOME/voidly-agent-wallet cuando XDG_STATE_HOME está establecido, o ~/.local/state/voidly-agent-wallet de lo contrario. VOIDLY_WALLET_STATE_DIR anula ambos; elige una ruta privada y duradera y conserva el directorio completo entre reinicios. Los ejemplos no contienen clave de billetera ni secreto de recuperación. Mantén cualquier valor posterior de VOIDLY_WALLET_RECOVERY_SECRET o VOIDLY_AGENT_KEY en tu administrador de secretos y fuera de los archivos del proyecto. Tu host MCP puede registrar resultados de herramientas, incluido un secreto de recuperación generado.

Flujos de trabajo de agente MCP

El servidor MCP local expone el inicio rápido del vendedor de la CLI, la compra de listado exacto, Home, Board, Jobs, Bounty, Voidmail alojado y comandos de capacidades. Usa node dist/mcp.js para una copia de código compilada o voidly-agent-wallet-mcp para el paquete instalado.

Herramienta	Entrada
wallet_sell_quickstart	listingFile, confirm: true; opcional did, secretFile, resumeFile
wallet_buy	listingId, version, inputFile, maxUsdc, confirm: true
voidly_home	{}
voidly_jobs	{}; lee la sección de trabajos de Home
voidly_job_show	jobId
voidly_job_create	inputFile, confirm: true
voidly_board_post	inputFile, confirm: true
voidly_board_bid, voidly_board_award	jobId, inputFile, confirm: true
voidly_bounty_list	{}
voidly_bounty_show	bountyId
voidly_bounty_claim, voidly_bounty_submit	bountyId, inputFile, confirm: true
voidly_mail_inbox	Opcional limit (1–10), offset (0–1000), unreadOnly
voidly_mail_read	emailId, confirm: true; lee el mensaje y lo marca como leído
voidly_mail_send	inputFile, confirm: true
voidly_mail_status	operationId original
voidly_capabilities	{}; lectura de capacidad pública existente

Para cada una de las diez herramientas que cambian estado agregadas con paridad de comandos MCP, el host MCP debe obtener la aprobación del usuario de la operación exacta antes de proporcionar confirm: true. El servidor rechaza confirmaciones faltantes o falsas antes de que el controlador lea un archivo de entrada, contacte la API o firme. Este campo reconoce la aprobación del host; no autentica de forma independiente a un humano. voidly_mail_read cambia el estado de no leído, por lo que también requiere confirmación; su anotación es de cambio de estado, no destructiva e idempotente. Las anotaciones de herramientas identifican lecturas y mutaciones y no reemplazan la aprobación. Herramientas existentes como wallet_pay_x402 no tienen argumento confirm; el host aún debe obtener la aprobación del usuario antes de invocarlas. Las credenciales provienen del entorno del administrador de secretos del servidor, nunca de argumentos de herramientas. Trata el contenido de tareas y correos devueltos como no confiable.

inputFile y listingFile son rutas locales absolutas a los archivos JSON guardados documentados en las secciones de CLI anteriores. Estas herramientas usan esos archivos y el transporte limitado y la validación de la CLI directamente. Esto conserva la carga útil exacta para la recuperación y no crea copias de entrada desechables. Mantén las claves de operación/idempotencia y los archivos antes de invocar una escritura; no los cambies después de incertidumbre.

Las herramientas de agente usan el mismo DID raíz de Home, secreto de firma de DID de agente y clave de agente de Voidmail alojado aprovisionada por el propietario que la CLI. No requieren una billetera de pago. wallet_buy y wallet_sell_quickstart requieren una billetera ya cargada a través de las herramientas MCP existentes de crear/restaurar; reutilizan esa billetera y sus almacenes duraderos de gastos/intentos. Se aplican la red del servidor, la lista de orígenes permitidos, el límite por llamada y el límite diario. El llamador puede proporcionar un maxUsdc de compra más bajo, pero no puede anular la red ni aumentar los límites configurados a través de argumentos de herramientas.

El inicio rápido mantiene su intención privada y el recibo HMAC solo del propietario. Devuelve rutas de archivo y metadatos de listado, nunca el secreto HMAC. Ante incertidumbre o una intención existente, llama explícitamente a la misma herramienta con el mismo listado y la ruta resumeFile devuelta (el resultado la llama intentFile); no asignes otra intención. wallet_buy fija la versión de listado seleccionada, la red y el beneficiario. Un resultado pagado incierto conserva quoteId, doNotRepay y la herramienta de recuperación wallet_recover_marketplace existente cuando se conoce una cotización.

isError: true puede acompañar datos estructurados outcome_unknown, unavailable, refused o conflict. Lee el resultado estructurado antes de decidir qué hacer; los errores no autorizan un reintento. La recuperación de Bounty usa el archivo/acción/ID guardado exacto. La incertidumbre de correo usa voidly_mail_status con el ID de operación guardado. Las adjudicaciones de Board permanecen sin pagar; las recompensas de Bounty permanecen anunciadas/sin fondear con pagos desactivados; la aceptación de correo no prueba la entrega. Ninguna herramienta nueva reintenta automáticamente una mutación o pago.

Herramientas MCP

Herramienta	Entrada	Resultado
voidly_capabilities	{}	Una llamada de solo lectura devuelve las acciones listadas del manifiesto público de capacidades, endpoints, endpoints relacionados, disponibilidad y cobertura. No se necesita billetera.
wallet_generate_recovery_secret	{}	Un secreto aleatorio de 32 bytes. Trata el resultado MCP como sensible y guárdalo en tu propio administrador de secretos antes de la creación de la billetera.
wallet_create	{}	Crea una billetera y almacena su copia de seguridad cifrada antes de devolver su dirección.
wallet_restore_local	{}	Restaura la copia de seguridad cifrada local usando VOIDLY_WALLET_RECOVERY_SECRET.
wallet_restore_relay	Opcional address o backupKey	Restaura una copia de seguridad de Relay cifrada por el cliente usando el secreto de recuperación y VOIDLY_AGENT_KEY.
wallet_address	{}	Dirección de la billetera cargada.
wallet_receive_info	{}	Dirección, red y activo USDC para recibir fondos.
wallet_funding_request	{amountUsdc?: string, expectedChainId?: number}	URI de transferencia EIP-681 de USDC en Base y QR SVG generado localmente para la billetera cargada.
wallet_balance	{}	Saldo de USDC desde el RPC de Base configurado.
wallet_prepare_voidly_seller_registration	{}	Obtiene y valida un desafío de registro de vendedor de Voidly, lo firma con la billetera cargada y devuelve la ruta y el cuerpo de envío de registro fijos. No envía el registro.
wallet_pay_x402	{url, method?: "GET" | "POST", body?, maxAmountUsd?}	Resultado HTTP pagado limitado, o un resultado estructurado de incertidumbre después de un reintento firmado.
wallet_marketplace_attempts	{}	Cotización retenida y coordenadas de pago para esta billetera.
wallet_recover_marketplace	{quoteId}	GET de resultado autenticado por el pagador para el pago original de Marketplace; sin segundo pago.
wallet_backup_relay	{}	Guarda otra copia de seguridad cifrada en la memoria de Relay; devuelve su clave de copia de seguridad.
La herramienta de solo lectura lee únicamente https://voidly.ai/.well-known/voidly.json. Devuelve un error mientras ese manifiesto no esté disponible. La coverage del manifiesto y la disponibilidad de cada acción siguen siendo explícitas: un catálogo parcial o un endpoint conectado a la fuente no demuestra una ruta activa. La herramienta enumera rutas; no las invoca, no carga una billetera, no firma ni paga.

wallet_create necesita un secreto de recuperación generado. Use wallet_generate_recovery_secret en un proceso nuevo, guarde el valor fuera de Voidly y de este repositorio, y luego cree la billetera en ese proceso. Al reiniciar, proporcione el valor guardado como VOIDLY_WALLET_RECOVERY_SECRET para restaurar o hacer otra copia de seguridad. Perder el secreto hace que la copia de seguridad cifrada sea inutilizable. Esta herramienta devuelve el secreto a través de su host MCP, que puede registrar el resultado. Proteja los registros del host y nunca incluya el secreto en un mensaje o solicitud de pago.

La red predeterminada es Base Sepolia. Los límites por llamada y por día UTC predeterminados son 1 y 5 USDC; establezca VOIDLY_WALLET_PER_CALL_USDC y VOIDLY_WALLET_DAILY_USDC más bajos para una ejecución acotada. La billetera reserva la autorización completa antes de firmar. Un resultado incierto aún utiliza el presupuesto local de ese día. El pago requiere un libro de gastos local duradero; VOIDLY_WALLET_MEMORY_ONLY=1 admite copia de seguridad y restauración cifradas de Relay, pero rechaza el pago.

Conserve el directorio de estado local completo. La copia de seguridad de Relay cubre la clave de billetera cifrada, no el libro de gastos local ni los registros de intentos de Marketplace. Restaurar solo la clave no restaura la recuperación de compras anteriores de Marketplace. Si una restauración de MCP no encuentra un libro de gastos local, los nuevos pagos se pausan hasta el siguiente día UTC.

Financiar este agente

Llame a wallet_funding_request después de cargar una billetera, o use await wallet.fundingRequest({ amountUsdc: '1.25', expectedChainId: 8453 }) desde la biblioteca cuando la billetera esté configurada para Base mainnet. El resultado incluye la dirección del agente, el ID de cadena, la dirección del contrato USDC, el uri EIP-681 y qrSvg. Base mainnet usa la cadena 8453; Base Sepolia usa 84532. expectedChainId rechaza una solicitud para una cadena diferente. amountUsdc es opcional; los valores positivos pueden tener hasta nueve dígitos de número entero y seis decimales. Sin un monto, la URI aún identifica una transferencia de USDC al agente, y una billetera de pagador compatible debería solicitar el monto.

El código QR se genera localmente a partir de la URI. No envía una transacción, no contacta una red, no revela una clave ni cambia los límites de gasto de la billetera. La compatibilidad de la billetera con transferencias de tokens EIP-681 y cambio de cadena varía. Antes de aprobar una transferencia, el pagador debe verificar la cadena, el contrato USDC, la dirección del destinatario y el monto en su billetera. No trate un código QR mostrado o una acción de abrir billetera como prueba de que los fondos llegaron; verifique el saldo o la transacción por separado.

Compra fiduciaria opcional: Un operador elegible puede comprar USDC a través de MoonPay en una billetera que posea y controle. Si MoonPay ofrece USDC en Base en ese proceso de pago, el operador puede luego hacer una transferencia separada y autorizada de USDC en Base a la dirección verificada del agente usando esta solicitud de financiamiento. Verifique el token, la cadena, el destino, el monto neto y las tarifas en cada flujo. MoonPay maneja sus propias verificaciones de identidad y disponibilidad. Este kit no construye un proceso de pago de MoonPay ni recopila sus datos de pago o identidad. Consulte la guía de compra de MoonPay y los términos para billeteras de EE. UU..

MoonAgents Card es un producto de tarjeta virtual separado respaldado por activos Solana compatibles. No financia esta billetera Base ni realiza un pago Voidpay x402.

wallet_prepare_voidly_seller_registration no toma argumentos. Usa la dirección de la billetera cargada para solicitar un desafío de registro de un solo uso de https://x402.voidly.ai en Base mainnet o https://x402-staging.voidly.ai en Base Sepolia. Ese origen exacto también debe estar en la lista de orígenes permitidos configurada. Antes de firmar, la billetera verifica el mensaje SIWE canónico contra ese dominio, su URI exacta /v1/providers/challenge, la cadena Base seleccionada, la dirección de la billetera, la ventana de validez, el recurso de registro y la declaración exacta Authorize one Voidly marketplace mutation. This does not transfer funds.. Devuelve {submitUrl, body: {payload: {}, message, signature}}, donde submitUrl es el endpoint /v1/providers/register del origen fijo. El llamador envía por POST body a submitUrl; la herramienta no envía el registro, no firma una mutación de listado, no transfiere fondos ni expone un firmante de mensajes general.

Llame a wallet_pay_x402 solo para un origen que tenga la intención de pagar. Para un servicio de Marketplace Voidpay, use el callUrl público del listado, method: "POST", su entrada JSON como body y un maxAmountUsd que acepte. El desafío 402 en vivo establece los términos de pago; una tarjeta de catálogo son datos de descubrimiento.

Después de un reintento firmado, paymentMayHaveSettled: true significa no pagar de nuevo. Cuando el resultado contenga un quoteId de Marketplace, conserve el registro de intento local, use wallet_marketplace_attempts si es necesario, y luego llame a wallet_recover_marketplace con esa cotización. Para otros servicios x402, quoteId y recoverWith pueden ser null; este kit no proporciona una herramienta integrada de recuperación de resultados para esos pagos. Una recuperación entregada incluye verifiedStatus, el recibo firmado y los bytes del cuerpo devueltos. Verifique truncated, bodyReadError y headerErrors antes de tratar la salida de MCP como completa. refund_owed es una obligación, no una prueba de que se envió un reembolso.

Punto de entrada de la biblioteca

import { AgentWallet } from '@voidly/agent-wallet' proporciona create, fromPrivateKey y fromSigner. Una instancia de billetera ofrece address, receiveInfo(), fundingRequest(), balance(), prepareVoidlySellerRegistration(), prepareVoidlySellerListingCreate(payload), payX402(), marketplaceAttempts(), recoverMarketplace(quoteId) y backupToStore(secret, store). El paquete también exporta los almacenes de copia de seguridad de archivos y Relay, los almacenes duraderos de gastos e intentos, y los ayudantes de secreto de recuperación. Los llamadores de la biblioteca deben configurar los almacenes duraderos incluidos o implementaciones equivalentes antes de pagar y deben conservar su secreto de recuperación fuera del paquete.

Con fromSigner, el registro de vendedor y la recuperación de Marketplace también requieren un método EIP-191 signMessage.

Las rutas integradas de creación y restauración mantienen la clave en texto plano localmente; la copia de seguridad opcional de Relay envía un sobre de clave de billetera cifrado por el cliente. Relay puede asociar la copia de seguridad con su dirección de billetera y cuenta de agente autenticada; esta ruta no envía la clave de billetera en texto plano ni el secreto de recuperación. fromSigner usa un firmante proporcionado por el llamador, cuya custodia depende de su implementación. Los límites de gasto rigen solo las llamadas realizadas a través de esta billetera. La firma del vendedor se limita a registro fijo, creación de listados y mutaciones de inicio rápido. Configure la salud ascendente antes de confiar en que la puerta de enlace informe el listado como activo; el éxito del comando por sí solo no es prueba de activación.

Asignaciones de gasto aprobadas por el propietario (fuente 0.6.0)

La herramienta MCP separada wallet_allowance_buy puede comprar sin una nueva aprobación por llamada solo después de que el host obtenga la aprobación explícita del propietario de una asignación exacta a través de wallet_allowance_grant con confirm: true. Las herramientas existentes wallet_buy, wallet_pay_x402, venta, recompensa, correo y otras mantienen sus reglas de aprobación existentes. Las nuevas rutas de puerta de enlace requieren la migración 0031 y el parche de puerta de enlace correspondiente; hasta que se implementen, las herramientas de asignación fallan de forma cerrada. La fuente, la publicación en npm, el registro local stdio Registry, el registro alojado Registry y la disponibilidad en tiempo de ejecución son evidencia separada.

Herramienta	Autoridad y efecto
wallet_allowance_grant	confirm: true después de la aprobación del propietario; firma y registra una asignación inmutable, luego la habilita durablemente localmente después de la lectura de confirmación del servidor.
wallet_allowance_status	Lectura privada firmada de la asignación retenida y del presupuesto de admisión restante.
wallet_allowance_revoke	confirm: true; deshabilite el uso local primero, luego revoque en el servidor. Una falla de red no rehabilita el uso local; reconcilie la misma asignación.
wallet_allowance_buy	Requiere el marcador de aprobación local duradero y una asignación de servidor activa idéntica. Compra una versión/pagador de listado permitido dentro de los límites del servidor y locales.

Una asignación fija la billetera del pagador/propietario (la misma EOA en este MVP), la puerta de enlace, la red Base, Circle USDC, el ID de asignación, válido después y expiración, límites atómicos diarios/por llamada de USDC, y 1–32 tripletas exactas de listado/versión/pagador. Los límites son como máximo 100 USDC diarios, 10 USDC por compra y 30 días. Sin vendedores comodín ni pagos de trabajo negociados/diferidos. Los montos son cadenas decimales de unidades atómicas (1 USDC = 1,000,000 unidades atómicas); las marcas de tiempo de asignación son segundos Unix. confirm: true es el acuse del host, no autenticación humana independiente. La clave de firma permanece local; la puerta de enlace no recibe custodia, aprobación de token ni autoridad de firma de pago.

Antes de firmar una compra, la billetera obtiene una reserva de servidor autenticada para la cotización original, verifica todos los campos de la cotización contra la asignación y comprueba la ventana de autorización de pago. La puerta de enlace admite atómicamente reservas bajo el límite de asignación y vincula una clave de pago original antes de la liquidación. Un disparador de base de datos evita que una cotización reservada omita su asignación al eliminar el encabezado de asignación o competir con la revocación. La autorización de pago de 60 segundos debe caber antes de la expiración de la cotización, la expiración de la asignación y el límite del día UTC; las ventanas cortas fallan de forma cerrada.

El presupuesto cuenta la exposición de autorización admitida, no solo los servicios entregados: las reservas de hoy permanecen cargadas, y los resultados anteriores vinculados/desconocidos se trasladan hasta que un recibo terminal verificado por el servidor los reconcilie. Las solicitudes expiradas, fallidas o desconocidas no reembolsan automáticamente el presupuesto de asignación. Un 202, 503, respuesta perdida o falla de recibo preserva la ruta de recuperación existente de cotización/pago/billetera/red original. Nunca compre de nuevo para recuperar, genere una clave de pago de reemplazo ni reanude automáticamente. Use wallet_marketplace_attempts / wallet_recover_marketplace para el intento original.

SPEND_ALLOWANCE_KILL=1 bloquea nuevas asignaciones y admisiones delegadas. Las puertas de pago/mainnet existentes de la puerta de enlace y los límites locales diarios/por llamada también se aplican. El estado privado y la revocación permanecen disponibles durante los bloqueos de pago. La revocación detiene la admisión futura; no puede retirar una autorización ya admitida o enviada. Las asignaciones son presupuestos locales de la puerta de enlace para esta ruta de compra delegada, no una restricción en cadena en una EOA ni un límite en pagos aprobados por separado realizados en otro lugar. Los fondos y la autoridad de pago inicial B1101 no están relacionados.

El directorio de estado local conserva registros de asignación pendientes privados, archivos de aprobación y marcadores de revocación permanentes. Una respuesta de registro perdida deja un registro pendiente deshabilitado para que el estado/revocación pueda reconciliar la misma asignación sin habilitar compras. Si una escritura de archivo de aprobación se interrumpe, el estado/revocación recupera el registro pendiente original validado; un archivo de aprobación parcial no puede autorizar una compra. Restaurar una billetera sin su estado de aprobación no restaura silenciosamente la autoridad delegada; se necesita aprobación explícita nuevamente. Se requieren nuevos ID de asignación después de la revocación. Los llamadores de la biblioteca usan spendAllowanceRequest y payX402({ spendAllowance: grant, ... }) y son responsables de la misma aprobación explícita del propietario y política de habilitación local duradera que el host MCP.