---
title: "Mint the caller's Lightning wallet"
method: POST
path: "/agent/v1/lightning-wallet"
tags: ["Billing"]
---

# Mint the caller's Lightning wallet

`POST /agent/v1/lightning-wallet`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/agent/v1/lightning-wallet`
- Auth: API key in header `SIGN-IN-WITH-X`

Asks the platform for one budgeted, isolated Lightning sub-wallet on Run402's own Hub for the calling agent principal (`run402 init lightning`). Idempotent per principal: a live wallet is returned as is and nothing is minted twice. The platform-side broker mints the sub-wallet, so the first call usually answers `202` with `status: "minting"`; poll `GET /agent/v1/lightning-wallet`. The one response that first observes the wallet `active` carries `pairing` (the NWC pairing URI, a bearer secret shown exactly once and never recoverable); every later response reports `has_pairing` only. Custody is the platform Hub (`custody: "run402_hub"`): the sats sit on Run402's Hub and the agent holds a budgeted connection. `budget_sats` is the platform-set spending cap and `starter_sats` the amount the platform funded at mint.

## Headers

- `SIGN-IN-WITH-X` string, required

## Response `200`

The wallet exists (replay); no pairing is included.

- AgentLightningWallet: An agent principal's Lightning wallet: a budgeted, isolated sub-wallet on Run402's Hub. `pairing` appears exactly once, on the response that first hands it out.
  - `wallet_id` string, required
  - `status` 'minting' | 'active' | 'revoking' | 'revoked' | 'failed', required
  - `network` 'regtest' | 'signet' | 'mainnet', required
  - `custody` 'run402_hub', required
  - `custody_note` string
  - `lightning_address` string, nullable
  - `budget_sats` integer, required
  - `starter_sats` integer, required
  - `has_pairing` boolean, required
  - `pairing` string: The NWC pairing URI. Present exactly once; store it in the local profile and never send it to Run402.
  - `pairing_claimed_at` string, date-time, nullable
  - `failure_reason` string, nullable
  - `created_at` string, date-time, required
  - `activated_at` string, date-time, nullable
  - `revoked_at` string, date-time, nullable
  - `next_actions` NextAction[], required
    - `type` string, required: Advisory machine-readable action type such as retry, authenticate, submit_payment, fund_wallet, renew_tier, check_usage, resume_deploy, edit_request, edit_migration, contact_support, upgrade_client, poll (poll the project events feed — appended when the envelope carries a correlated_platform_incident), or hand_to_member (on a commit/promote response that just activated a public site: show the human urls.site and urls.console, relay Run402's offer to promote the build on @run402com, and ask yes or no — see `credited_as` below).
    - `method` string
    - `path` string
    - `auth` string
    - `why` string
    - `credited_as` string, nullable: `hand_to_member` only. The caller's own live presence name in the project's default room, else that room's most recently active live presence, else `null` — in which case `why` tells the agent that joining the room with a name (`run402 rooms join --name ...`) is how the promotion credits it.
    - `body` object: `hand_to_member` only. A ready-to-send `POST /feedback/v1` template: `{ project_id, message: "promote: yes", handle? }`.

## Other responses

- `201`: The wallet is active and this response hands out the pairing secret, exactly once.
- `202`: The platform is minting the wallet; poll the GET route.
- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.
- `503`: `LIGHTNING_WALLET_NOT_AVAILABLE` — the platform Hub is not configured or not ready; pay over x402 from the Base wallet meanwhile.

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)