API Endpoints npubcash v2

This document provides a comprehensive reference for all npubcash-server v2 API endpoints.

Base URL

All API endpoints are prefixed with /api/v2. For example, if your server is hosted at https://npub.cash, the full URL for the quotes endpoint would be https://npub.cash/api/v2/wallet/quotes.

Authentication

Most endpoints require authentication. See the Authentication guide for details on NIP-98 and JWT authentication methods.

Wallet Endpoints

Get All Quotes

Retrieve all quotes associated with the authenticated user.

Endpoint: GET /api/v2/wallet/quotes

Authentication: Required (NIP-98 or JWT Bearer)

Query Parameters:

• since (optional): Unix timestamp in seconds. If provided, only returns quotes updated since this time.

Response:

{
  "error": false,
  "data": [
    {
      "id": "quote-id-123",
      "amount": 1000,
      "mint": "https://mint.example",
      "bolt11": "lnbc10u1p3...",
      "paid": true,
      "createdAt": 1234567890,
      "updatedAt": 1234567890
    }
  ]
}

Example:

# Using JWT Bearer token
curl -X GET "https://npub.cash/api/v2/wallet/quotes" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..."

# Using NIP-98
curl -X GET "https://npub.cash/api/v2/wallet/quotes" \
  -H "Authorization: Nostr eyJpZCI6ImZlOTY0ZTc1ODkwMzM..."

# With since parameter
curl -X GET "https://npub.cash/api/v2/wallet/quotes?since=1234567890" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..."

Get Quotes Since

Retrieve quotes updated since a specific timestamp.

Endpoint: GET /api/v2/wallet/quotes

Authentication: Required (NIP-98 or JWT Bearer)

Query Parameters:

• since (required): Unix timestamp in seconds

Response: Same as Get All Quotes

Example:

curl -X GET "https://npub.cash/api/v2/wallet/quotes?since=1704067200" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..."

Settings Endpoints

Update Mint URL

Set or update the mint URL for the authenticated user.

Endpoint: PUT /api/v2/settings/mint

Authentication: Required (NIP-98 or JWT Bearer)

Request Body:

{
  "mintUrl": "https://mint.example"
}

Response:

{
  "error": false,
  "data": {
    "pubkey": "npub1...",
    "mintUrl": "https://mint.example",
    "lockQuotes": false
  }
}

Example:

curl -X PUT "https://npub.cash/api/v2/settings/mint" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..." \
  -H "Content-Type: application/json" \
  -d '{"mintUrl": "https://mint.example"}'

Lock/Unlock Quotes

Lock or unlock quotes for the authenticated user. When locked, quotes cannot be claimed.

Endpoint: PUT /api/v2/settings/lock

Authentication: Required (NIP-98 or JWT Bearer)

Request Body:

{
  "lockQuotes": true
}

Response:

{
  "error": false,
  "data": {
    "pubkey": "npub1...",
    "mintUrl": "https://mint.example",
    "lockQuotes": true
  }
}

Example:

curl -X PUT "https://npub.cash/api/v2/settings/lock" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..." \
  -H "Content-Type: application/json" \
  -d '{"lockQuotes": true}'

Authentication Endpoints

Get JWT Token

Exchange a NIP-98 authentication header for a JWT bearer token.

Endpoint: GET /api/v2/auth/nip98

Authentication: Required (NIP-98 only)

Response:

{
  "error": false,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR..."
  }
}

Example:

curl -X GET "https://npub.cash/api/v2/auth/nip98" \
  -H "Authorization: Nostr eyJpZCI6ImZlOTY0ZTc1ODkwMzM..."

The returned token can be used as a Bearer token for subsequent requests:

curl -X GET "https://npub.cash/api/v2/wallet/quotes" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..."

WebSocket Endpoints

Quote Updates

Subscribe to real-time quote updates via WebSocket.

Endpoint: wss://npub.cash/api/v2/ws/quote

Authentication: NIP-98 challenge/response

Protocol:

1. Client connects to the WebSocket endpoint
2. Server sends a challenge message:

   {
     "type": "challenge",
     "challenge": "random-challenge-string"
   }

3. Client responds with a NIP-98 signed authentication:

   {
     "type": "auth",
     "token": "Nostr eyJpZCI6ImZlOTY0ZTc1ODkwMzM..."
   }

4. Server validates and sends confirmation:

   {
     "type": "ok"
   }

5. Server sends update messages when quotes change:

   {
     "type": "update",
     "quoteId": "quote-id-123"
   }

Example (JavaScript):

const ws = new WebSocket("wss://npub.cash/api/v2/ws/quote");

ws.onmessage = async (event) => {
  const message = JSON.parse(event.data);

  if (message.type === "challenge") {
    // Sign the challenge using NIP-98
    const token = await signNip98Challenge(message.challenge);
    ws.send(
      JSON.stringify({
        type: "auth",
        token: token,
      })
    );
  } else if (message.type === "update") {
    console.log("Quote updated:", message.quoteId);
  }
};

Lightning Address Endpoints

LNURL Pay Request

Handle Lightning Address payment requests (LUD-16).

Endpoint: GET /.well-known/lnurlp/{npub}

Authentication: Not required (public endpoint)

Path Parameters:

• npub: Nostr public key (npub format)

Query Parameters:

• amount (optional): Amount in millisatoshis

Response:

{
  "tag": "payRequest",
  "commentAllowed": 0,
  "callback": "https://npub.cash/api/v2/lnurl/{npub}",
  "metadata": "[[\"text/plain\",\"Payment to npub1...\"]]",
  "minSendable": 1000,
  "maxSendable": 1000000
}

Example:

curl "https://npub.cash/.well-known/lnurlp/npub1mhcr4j594hsrnen594d7700n2t03n8gdx83zhxzculk6sh9nhwlq7uc226"

LNURL Callback

Generate a Lightning invoice for a payment request.

Endpoint: GET /api/v2/lnurl/callback/{npub}

Authentication: Not required (public endpoint)

Path Parameters:

• npub: Nostr public key (npub format)

Query Parameters:

• amount: Amount in millisatoshis (required)

Response:

{
  "status": "OK",
  "pr": "lnbc10u1p3...",
  "routes": []
}

Example:

curl "https://npub.cash/api/v2/lnurl/callback/npub1...?amount=100000"

Error Responses

All endpoints return errors in a consistent format:

{
  "error": true,
  "message": "Error description"
}

Common HTTP Status Codes:

• 200 OK: Request succeeded
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Authentication required or invalid
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

Example Error Response:

{
  "error": true,
  "message": "Invalid authentication token"
}