API docs by Redocly

npubcash HTTP API (2.0.0)

Download OpenAPI specification:

License: MIT

HTTP endpoints exposed by npubcash-server. WebSocket authentication and quote updates are documented separately because OpenAPI describes HTTP.

Provider

Public provider capabilities and feature terms.

Discover provider capabilities

Returns public feature availability and advisory payment terms. A payment request returned by a later 402 response remains authoritative.

Responses

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    }
}

Wallet

Paid Cashu mint quotes associated with a Nostr identity.

List paid mint quotes

Authorizations:
Nip98BearerAuth
query Parameters
since
integer >= 0

Return quotes paid after this Unix timestamp in seconds.

limit
integer [ 1 .. 1000 ]
Default: 50

Requested page size. The server caps the result at 50.

offset
integer >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    },
  • "metadata": {
    }
}

User

User settings and paid username registration.

Get user settings

Authorizations:
Nip98BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    }
}

Set the preferred mint for future payments

Authorizations:
Nip98BearerAuth
Request Body schema: application/json
required
mint_url
required
string <uri>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    }
}

Configure locking for future quotes

Authorizations:
Nip98BearerAuth
Request Body schema: application/json
required
lockQuotes
required
boolean

Responses

Request samples

Content type
application/json
{
  • "lockQuotes": true
}

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    }
}

Purchase a username with Cashu

Authorizations:
Nip98BearerAuth
header Parameters
X-Cashu
string

Cashu token satisfying the payment request.

Request Body schema: application/json
required
username
required
string >= 3 characters ^(?!npub1)[a-zA-Z0-9]+$

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    }
}

Authentication

NIP-98 to JWT authentication exchange.

Exchange NIP-98 authorization for a JWT

Authorizations:
Nip98

Responses

Response samples

Content type
application/json
{
  • "error": false,
  • "data": {
    }
}

Lightning Address

Public LNURL-pay discovery, invoice creation, and payment verification.

Discover a recipient or request an invoice

Without amount, returns an LNURL-pay discovery response. With an amount in millisatoshis, returns a BOLT11 invoice and a verification URL.

path Parameters
user
required
string

An npub or purchased username.

query Parameters
amount
integer >= 1

Invoice amount in millisatoshis.

nostr
string

URL-encoded Nostr zap request.

Responses

Response samples

Content type
application/json
Example
{
  • "callback": "http://example.com",
  • "minSendable": 0,
  • "maxSendable": 0,
  • "metadata": "[[\"text/plain\",\"A cashu lightning address... Neat!\"],[\"text/identifier\",\"alice@npub.cash\"]]",
  • "tag": "payRequest",
  • "allowsNostr": true,
  • "nostrPubkey": "string"
}

Check whether an LNURL invoice has been paid

Follow the verify URL returned when requesting an invoice. The token grants access to that invoice's status without authentication. Settlement reflects persisted PAID or ISSUED state from background mint monitoring and may lag the payment. The preimage is always null, including after settlement, because Cashu mint quotes do not expose it. Clients requiring a preimage as proof of payment cannot use this response for that purpose.

path Parameters
token
required
string^[0-9a-f]{64}$

Opaque verification token supplied in the callback response.

Responses

Response samples

Content type
application/json
Example
{
  • "status": "OK",
  • "settled": true,
  • "preimage": null,
  • "pr": "string"
}

NIP-05

Public NIP-05 username resolution.

Resolve a purchased username to a Nostr public key

query Parameters
name
string

Purchased username to resolve. When omitted or unknown, the server returns empty name and relay mappings.

Responses

Response samples

Content type
application/json
Example
{}