Billing

Mint the caller's Lightning wallet

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.

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

Headers

SIGN-IN-WITH-Xstring required

SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.

Response

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

wallet_idstring required
status'minting' | 'active' | 'revoking' | 'revoked' | 'failed' required
network'regtest' | 'signet' | 'mainnet' required
custody'run402_hub' required
custody_notestring
lightning_addressstring nullable
budget_satsinteger required
starter_satsinteger required
has_pairingboolean required
pairingstring

The NWC pairing URI. Present exactly once; store it in the local profile and never send it to Run402.

pairing_claimed_atstring date-time nullable
failure_reasonstring nullable
created_atstring date-time required
activated_atstring date-time nullable
revoked_atstring date-time nullable

Example response

{
  "wallet_id": "lw_3f9c1e2b4d5a6f7081920a1b2c3d4e5f",
  "next_actions": [
    {
      "method": "POST",
      "path": "/tiers/v1/hobby",
      "auth": "x402"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.