Wallet

Wallet Management (Bitcoin Lightning)

Wallet Authentication

• POST /wallet/auth: Authorizes access to wallet functions for an administrator.

  • Authorization: Requires administrator token.
  • Request Body:

  {
    "password": "string"
  }

  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/auth" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ 
      "password": "S3cur3P4ssw0rd!!"
    }'

  • Response Body (200 OK):

  {
    "message": "Login successful"
  }

  • Response Headers: Sets the walletAccessToken cookie.

• POST /wallet/logout: Logs out of the wallet and deletes the access cookie.

  • Authorization: Requires administrator token.
  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/logout" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN"

  • Response Body (200 OK):

  {
    "status": "ok"
  }

  • Response Headers: Deletes the walletAccessToken cookie.

The wallet endpoints allow you to manage the Bitcoin Lightning wallet integrated into the POS system.

• GET /wallet/getinfo: Gets information from the Lightning node.

  • Authorization: Requires JWT authentication (admin)
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/getinfo" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

  • Response Body (Success - 200 OK):

  {
    "nodeId": "03a1b2c3d4e5f6789012345678901234567890abcdef",
    "channels": [
      {
        "state": "NORMAL",
        "channelId": "0x1234567890abcdef",
        "balanceSat": 1000000,
        "inboundLiquiditySat": 500000,
        "capacitySat": 1500000,
        "fundingTxId": "abcdef1234567890"
      }
    ],
    "chain": "mainnet",
    "blockHeight": 800000,
    "version": "0.6.0"
  }

• GET /wallet/getbalance: Gets the balance of the Lightning wallet.

  • Authorization: Requires JWT authentication (admin)
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/getbalance" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

  • Response Body (Success - 200 OK):

  {
    "balanceSat": 1000000,
    "feeCreditSat": 5000
  }

• POST /wallet/invoice: Creates a Lightning invoice. Requires only JWT (no walletAccessToken) — ideal for creating invoices from the checkout flow without exposing wallet credentials.

  • Authorization: Requires accessToken (JWT)
  • Request Body: Same as /wallet/createinvoice
  • Response Body (200 OK): Same as /wallet/createinvoice

• POST /wallet/createinvoice: Creates a Lightning invoice to receive payments.

  • Authorization: Requires JWT authentication
  • Request Body:

  {
    "description": "string",
    "amountSat": 1000,
    "externalId": "string",
    "expirySeconds": 3600
  }

  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/createinvoice" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ 
      "description": "Payment for order #123",
      "amountSat": 50000,
      "externalId": "order-123",
      "expirySeconds": 3600
    }'

  • Response Body (Success - 200 OK):

  {
    "amountSat": 50000,
    "paymentHash": "abcdef1234567890abcdef1234567890abcdef12",
    "serialized": "lnbc500u1p3xnhl2pp5..."
  }

• POST /wallet/payinvoice: Pays a Lightning invoice.

  • Authorization: Requires JWT authentication (admin)
  • Request Body:

  {
    "amountSat": 1000,
    "invoice": "string"
  }

  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/payinvoice" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ 
      "amountSat": 25000,
      "invoice": "lnbc250u1p3xnhl2pp5..."
    }'

  • Response Body (Success - 200 OK):

  {
    "recipientAmountSat": 25000,
    "routingFeeSat": 100,
    "paymentId": "payment-uuid-123",
    "paymentHash": "abcdef1234567890",
    "paymentPreimage": "1234567890abcdef"
  }

• POST /wallet/payoffer: Pays a BOLT12 offer.

  • Authorization: Requires JWT authentication (admin)
  • Request Body:

  {
    "amountSat": 1000,
    "offer": "string",
    "message": "string"
  }

  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/payoffer" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ 
      "amountSat": 30000,
      "offer": "lno1qcp4256wpj...",
      "message": "Payment for service"
    }'

  • Response Body (Success - 200 OK):

  {
    "recipientAmountSat": 30000,
    "routingFeeSat": 150,
    "paymentId": "payment-uuid-456",
    "paymentHash": "fedcba0987654321",
    "paymentPreimage": "0987654321fedcba"
  }

• POST /wallet/payonchain: Makes an on-chain Bitcoin payment.

  • Authorization: Requires JWT authentication (admin)
  • Request Body:

  {
    "amountSat": 100000,
    "address": "string",
    "feerateSatByte": 10
  }

  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/payonchain" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ 
      "amountSat": 100000,
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "feerateSatByte": 15
    }'

  • Response Body (Success - 200 OK):

  {
    "txId": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "amountSat": 100000,
    "feesSat": 2250
  }

• POST /wallet/bumpfee: Increases the fee of an on-chain transaction.

  • Authorization: Requires JWT authentication (admin)
  • Request Body:

  20

  • cURL Example:

  curl -X POST "http://127.0.0.1:9154/wallet/bumpfee" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '25'

  • Response Body (Success - 200 OK):

  {
    "txId": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
    "newFeerateSatByte": 25,
    "additionalFeesSat": 1500
  }

• POST /wallet/decodeinvoice: Decodes a Lightning invoice and returns its amount and description.

  • Authorization: Requires accessToken + walletAccessToken
  • Request Body:

  {
    "invoice": "lnbc500u1p3xnhl2pp5..."
  }

  • Response Body (200 OK):

  {
    "amountSat": 50000,
    "description": "Payment for order #123"
  }

  • Response Body (400 Bad Request):

  { "error": "Could not decode invoice" }

• POST /wallet/closechannel: Closes a Lightning channel.

  • Authorization: Requires accessToken + walletAccessToken
  • Request Body:

  {
    "channelId": "string",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "feerateSatByte": 10
  }

  • Response Body (200 OK): Result from Phoenix service.

• POST /wallet/export: Exports the transaction history in CSV format.

  • Authorization: Requires accessToken + walletAccessToken
  • Request Body:

  {
    "from": "2024-01-01",
    "to": "2024-12-31"
  }

  • Response Body (200 OK): CSV export result.

• GET /wallet/seed: Retrieves the wallet seed (mnemonic).

  • Authorization: Requires accessToken + walletAccessToken
  • Response Body (200 OK): Seed data from Phoenix.

warning

Exposes the wallet seed. Only use in secure, controlled contexts — never in production without explicit justification.

Payment Management

• GET /wallet/payments/incoming: Lists incoming payments.

  • Authorization: Requires JWT authentication (admin)
  • Query Parameters:
    • from (long): Start timestamp
    • to (long): End timestamp
    • limit (int): Result limit (default: 20)
    • offset (int): Offset for pagination (default: 0)
    • all (boolean): Include all payments (default: false)
    • externalId (string): Specific external ID
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/payments/incoming?limit=10&offset=0" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

  • Response Body (Success - 200 OK):

  [
    {
      "paymentHash": "abcdef1234567890",
      "amountSat": 50000,
      "receivedSat": 50000,
      "description": "Payment for order #123",
      "externalId": "order-123",
      "createdAt": 1640995200000,
      "completedAt": 1640995300000,
      "status": "RECEIVED"
    }
  ]

• GET /wallet/payments/incoming/{paymentHash}: Gets a specific incoming payment.

  • Authorization: Requires JWT authentication (admin)
  • Path Parameters:
    • paymentHash (string): Payment hash
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/payments/incoming/abcdef1234567890" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

• GET /wallet/payments/outgoing: Lists outgoing payments.

  • Authorization: Requires JWT authentication (admin)
  • Query Parameters:
    • from (long): Start timestamp
    • to (long): End timestamp
    • limit (int): Result limit (default: 20)
    • offset (int): Offset for pagination (default: 0)
    • all (boolean): Include all payments (default: false)
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/payments/outgoing?limit=10" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

• GET /wallet/payments/outgoing/{paymentId}: Gets an outgoing payment by ID.

  • Authorization: Requires JWT authentication (admin)
  • Path Parameters:
    • paymentId (string): Payment ID
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/payments/outgoing/payment-uuid-123" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

• GET /wallet/payments/outgoingbyhash/{paymentHash}: Gets an outgoing payment by hash.

  • Authorization: Requires JWT authentication (admin)
  • Path Parameters:
    • paymentHash (string): Payment hash
  • cURL Example:

  curl -X GET "http://127.0.0.1:9154/wallet/payments/outgoingbyhash/abcdef1234567890" \
    -H "Cookie: accessToken=$ACCESS_TOKEN" \
    -H "Cookie: refreshToken=$REFRESH_TOKEN" \
    -H "Cookie: walletAccessToken=$WALLET_ACCESS_TOKEN" \
    -H "Content-Type: application/json"

Real-time Payment WebSocket

• GET /ws/payments: WebSocket connection to receive real-time Lightning payment notifications.
  • Authorization: Requires valid access token (JWT via cookie)
  • Protocol: WebSocket (ws:// or wss://)
  • Connection example:

  const ws = new WebSocket("ws://127.0.0.1:9154/ws/payments");
  ws.onmessage = (event) => console.log(JSON.parse(event.data));

  • Connection established message:

  { "type": "connected" }

  • Payment received message:

  {
    "type": "payment_received",
    "timestamp": 1712150400000,
    "amountSat": 50000,
    "paymentHash": "abcdef1234567890",
    "externalId": "order-123",
    "payerNote": "Payment for order #123"
  }

Important notes:

• Endpoints require JWT authentication via cookies (accessToken)
• Only /createinvoice is available for authenticated users, the rest require admin permissions
• Amounts are expressed in satoshis (1 BTC = 100,000,000 sats)
• Lightning invoices have a configurable expiration time
• On-chain payments require blockchain confirmations
• Phoenix Wallet must be configured and synchronized
• For production, ensure a secure connection with the Phoenix node