API docs by Redocly

UMA Auth API (0.1)

Download OpenAPI specification:Download

License: Apache 2.0

This API allows you to authenticate with the UMA server to take actions on a user's wallet. It's the exposed communication layer between the NWC server and the main UMA server.

UmaAuth

make_invoice: Create a new invoice

Authorizations:
bearerAuth
Request Body schema: application/json
amount
required
integer <int64> > 0

The amount to invoice in msats.

description
string

A memo to attach to the invoice.

description_hash
string

A hash of a longer description field.

expiry
integer > 0

The number of seconds until the invoice expires.

Responses

Request samples

Content type
application/json
{
  • "amount": 1000,
  • "description": "Payment for services rendered.",
  • "description_hash": "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15",
  • "expiry": 3600
}

Response samples

Content type
application/json
{
  • "type": "incoming",
  • "invoice": "lnbcrt1pjrsa37pp50geu5vxkzn4ddc4hmfkz9x308tw9lrrqtktz2hpm0rccjyhcyp5qdqh2d68yetpd45kueeqv3jk6mccqzpgxq9z0rgqsp5ge2rdw0tzvakxslmtvfmqf2fr7eucg9ughps5vdvp6fm2utk20rs9q8pqqqssqjs3k4nzrzg2nu9slu9c3srv2ae8v69ge097q9seukyw2nger8arj93m6erz8u657hfdzztfmc55wjjm9k337krl00fyw6s9nnwaafaspcqp2uv",
  • "description": "Pay for pizza.",
  • "description_hash": "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15",
  • "preimage": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "payment_hash": "7332c2671019264cf0e9b8626bde20c9c3979799c570a276fb9512e22aef1f08",
  • "amount": 1000,
  • "fees_paid": 1000,
  • "created_at": 1683148800,
  • "expires_at": 1683148800,
  • "settled_at": 1683148800,
  • "metadata": { }
}

pay_invoice: Pay a bolt11 invoice

Authorizations:
bearerAuth
Request Body schema: application/json
invoice
required
string

The bolt11 invoice to pay.

amount
integer or null <int64> > 0

The amount to pay for a 0-amount invoice.

budget_currency_code
string

The code of the currency the sender used to set budget. Optional if the budget is set in SAT.

Responses

Request samples

Content type
application/json
{
  • "invoice": "lntb1u1pw0k7jw",
  • "amount": 1000,
  • "budget_currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "preimage": "abcd1234",
  • "total_budget_currency_amount": 1000
}

lookup_invoice: Get an invoice by its payment hash

Authorizations:
bearerAuth
path Parameters
payment_hash
required
string
Example: f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

The payment hash of the invoice.

Responses

Response samples

Content type
application/json
{
  • "type": "incoming",
  • "invoice": "lnbcrt1pjrsa37pp50geu5vxkzn4ddc4hmfkz9x308tw9lrrqtktz2hpm0rccjyhcyp5qdqh2d68yetpd45kueeqv3jk6mccqzpgxq9z0rgqsp5ge2rdw0tzvakxslmtvfmqf2fr7eucg9ughps5vdvp6fm2utk20rs9q8pqqqssqjs3k4nzrzg2nu9slu9c3srv2ae8v69ge097q9seukyw2nger8arj93m6erz8u657hfdzztfmc55wjjm9k337krl00fyw6s9nnwaafaspcqp2uv",
  • "description": "Pay for pizza.",
  • "description_hash": "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15",
  • "preimage": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "payment_hash": "7332c2671019264cf0e9b8626bde20c9c3979799c570a276fb9512e22aef1f08",
  • "amount": 1000,
  • "fees_paid": 1000,
  • "created_at": 1683148800,
  • "expires_at": 1683148800,
  • "settled_at": 1683148800,
  • "metadata": { }
}

get_balance: Get the balance of the user's wallet

Authorizations:
bearerAuth
query Parameters
currency_code
string
Example: currency_code=USD

The currency code of the balance. Assumed to be in msats if not provided.

Responses

Response samples

Content type
application/json
{
  • "balance": 1000,
  • "currency": {
    }
}

lookup_user_by_lud16: Get receiver info by LUD16 address.

Authorizations:
bearerAuth
path Parameters
receiver_address
required
string
Example: $alice@vasp.net

The receiver's LUD16 address.

query Parameters
base_sending_currency_code
string
Example: base_sending_currency_code=USD

The currency code of the sender's balance. Assumed to be in msats if not provided. This is used to calculate the multiplier for the receiver's currencies.

Responses

Response samples

Content type
application/json
{
  • "currencies": [
    ]
}

fetch_quote_for_lud16: Get a quote for a payment to an LUD16 address

Authorizations:
bearerAuth
query Parameters
sending_currency_code
required
string
Example: sending_currency_code=MXN

The currency code being sent from the sender's wallet.

receiving_currency_code
required
string
Example: receiving_currency_code=USD

The currency code of the currency that the receiver will receive.

locked_currency_amount
required
integer <int64> > 0
Example: locked_currency_amount=1000

The amount to send/receive in the smallest unit of the locked currency (eg. cents). See locked_currency_side for more information.

locked_currency_side
required
string (LockedCurrencySide)
Enum: "sending" "receiving"

The side of the quote which should be locked and specified in the locked_currency_amount. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the locked_currency_amount to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the locked_currency_amount to 10000 (in cents).

receiver_address
required
string
Example: receiver_address=$alice@vasp.net

The LUD16 address to send the payment to.

Responses

Response samples

Content type
application/json
{
  • "sending_currency": {
    },
  • "receiving_currency": {
    },
  • "payment_hash": "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15",
  • "expires_at": 1683148800,
  • "multiplier": 123,
  • "fees": 10,
  • "total_sending_amount": 123010,
  • "total_receiving_amount": 1000,
  • "created_at": 1683148800
}

execute_quote: Execute a quote

Authorizations:
bearerAuth
path Parameters
payment_hash
required
string
Example: f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

The payment hash of the quote to execute.

Request Body schema: application/json
budget_currency_code
string

The code of the currency the sender used to set budget. Optional if it is the same as sending_currency_code.

Responses

Request samples

Content type
application/json
{
  • "budget_currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "preimage": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "total_budget_currency_amount": 1000
}

pay_to_lud16_address: Pay directly to an LNURL address based on a fixed sending amount.

Authorizations:
bearerAuth
Request Body schema: application/json
receiver_address
required
string

The LUD16 address to pay.

sending_currency_code
required
string

The code of the currency being sent from the sender's wallet.

sending_currency_amount
required
integer <int64> > 0

The amount to send in the smallest unit of the sending currency (eg. cents).

receiving_currency_code
string

The code of the currency being received by the receiver. If not provided, the receiver's default currency will be used.

budget_currency_code
string

The code of the currency the sender used to set budget. Optional if it is the same as sending_currency_code.

Responses

Request samples

Content type
application/json
{
  • "receiver_address": "$alice@vasp.net",
  • "sending_currency_code": "MXN",
  • "sending_currency_amount": 1000,
  • "receiving_currency_code": "USD",
  • "budget_currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "preimage": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "quote": {
    },
  • "total_budget_currency_amount": 1000
}

pay_keysend: Pay directly to the pubkey of the receiver node based on a fixed receiving amount

Authorizations:
bearerAuth
Request Body schema: application/json
amount
required
integer <int64> > 0

The amount to pay in msats.

pubkey
required
string

The public key of the receiver's node.

preimage
string

Preimage of the payment.

Array of objects

The tlv records.

budget_currency_code
string

The code of the currency the sender used to set budget. Optional if the budget is set to SAT.

Responses

Request samples

Content type
application/json
{
  • "amount": 10000,
  • "pubkey": "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
  • "preimage": 1000,
  • "tlv_records": [
    ],
  • "budget_currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "preimage": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "total_budget_currency_amount": 1000
}

get_info: Get information about the user's wallet connection

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "alias": "Alice's Wallet",
  • "color": "#FF0000",
  • "pubkey": "abcd1234",
  • "network": "testnet",
  • "block_height": 1000,
  • "block_hash": "abcd1234",
  • "methods": [
    ],
  • "lud16": "$alice@vasp.net",
  • "currencies": [
    ]
}

list_transactions: Lists invoices and payments

Authorizations:
bearerAuth
query Parameters
from
integer <int64>
Example: from=1683148800

Starting timestamp in seconds since epoch (inclusive).

until
integer <int64>
Example: until=1683148800

Ending timestamp in seconds since epoch (inclusive).

limit
integer > 0
Example: limit=10

Maximum number of transactions to return.

offset
integer >= 0
Example: offset=0

Offset of the first transaction to return.

unpaid
boolean
Example: unpaid=false

Whether to include unpaid invoices.

type
string (TransactionType)
Enum: "incoming" "outgoing"

Type of transactions to return: "incoming" for invoices, "outgoing" for payments, undefined for both.

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ]
}

get_budget_estimate: Estimate the total cost of the payment to complete the payment in the currency of sender's budget.

Authorizations:
bearerAuth
query Parameters
sending_currency_code
required
string
Example: sending_currency_code=SAT

The code of the currency that will be sent from the sender's wallet.

sending_currency_amount
required
integer <int64> > 0
Example: sending_currency_amount=1000

The amount to send in the smallest unit of the sending currency (eg. cents).

budget_currency_code
required
string
Example: budget_currency_code=USD

The code of the currency the sender used to set budget.

Responses

Response samples

Content type
application/json
{
  • "estimated_budget_currency_amount": 1000
}