payments-rest-api/openapi.json

{"openapi":"3.1.0","info":{"title":"Breez Nodeless Payments API","description":"A FastAPI implementation of Breez SDK for Lightning/Liquid payments","version":"1.0.0"},"paths":{"/list_payments":{"get":{"summary":"List Payments","operationId":"list_payments_list_payments_get","parameters":[{"name":"from_timestamp","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"From Timestamp"}},{"name":"to_timestamp","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Timestamp"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/receive_payment":{"post":{"summary":"Receive Payment","operationId":"receive_payment_receive_payment_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivePaymentBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/send_payment":{"post":{"summary":"Send Payment","operationId":"send_payment_send_payment_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPaymentBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/send_onchain":{"post":{"summary":"Send Onchain","operationId":"send_onchain_send_onchain_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendOnchainBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendOnchainResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/onchain_limits":{"get":{"summary":"Onchain Limits","operationId":"onchain_limits_onchain_limits_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/check_payment_status/{destination}":{"get":{"summary":"Check Payment Status","description":"Check the status of a payment by its identifier (payment hash, destination, or swap ID).\n\nThe payment states follow the SDK states directly:\n- PENDING: Swap service is holding payment, lockup transaction broadcast\n- WAITING_CONFIRMATION: Claim transaction broadcast or direct Liquid transaction seen\n- SUCCEEDED: Claim transaction or direct Liquid transaction confirmed\n- FAILED: Swap failed (expired or lockup transaction failed)\n- WAITING_FEE_ACCEPTANCE: Payment requires fee acceptance\n\nArgs:\n    destination: The payment identifier (payment hash, destination, or swap ID)\nReturns:\n    Payment status information including status, payment details, amount, fees, and timestamps\nRaises:\n    HTTPException: 404 if payment not found, 500 for other errors","operationId":"check_payment_status_check_payment_status__destination__get","parameters":[{"name":"destination","in":"path","required":true,"schema":{"type":"string","title":"Destination"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/exchange_rates/{currency}":{"get":{"summary":"Get Exchange Rate","description":"Get current exchange rates, optionally filtered by currency.\n\nArgs:\n    currency: Optional currency code (e.g., 'EUR', 'USD'). If not provided, returns all rates.\nReturns:\n    Exchange rate information for the specified currency or all available currencies.","operationId":"get_exchange_rate_exchange_rates__currency__get","parameters":[{"name":"currency","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/exchange_rates":{"get":{"summary":"Get All Exchange Rates","description":"Get all available exchange rates.\n\nReturns:\n    Dictionary of all available exchange rates.","operationId":"get_all_exchange_rates_exchange_rates_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/payment/{payment_id}":{"get":{"summary":"Get Payment Info","description":"Get detailed payment information for a specific BOLT11 invoice.\n\nArgs:\n    payment_id: The BOLT11 invoice string\nReturns:\n    Complete payment information if found, or a payment object with NOT_FOUND status\nRaises:\n    HTTPException: 400 if invalid invoice, 500 for unexpected errors","operationId":"get_payment_info_payment__payment_id__get","parameters":[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","title":"Payment Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/lnurl/parse_input":{"post":{"tags":["lnurl"],"summary":"Parse Input","operationId":"parse_input_v1_lnurl_parse_input_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseInputBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/lnurl/prepare":{"post":{"tags":["lnurl"],"summary":"Prepare","operationId":"prepare_v1_lnurl_prepare_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareLnurlPayBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/lnurl/pay":{"post":{"tags":["lnurl"],"summary":"Pay","operationId":"pay_v1_lnurl_pay_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LnurlPayBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/lnurl/auth":{"post":{"tags":["lnurl"],"summary":"Auth","operationId":"auth_v1_lnurl_auth_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LnurlAuthBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/lnurl/withdraw":{"post":{"tags":["lnurl"],"summary":"Withdraw","operationId":"withdraw_v1_lnurl_withdraw_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LnurlWithdrawBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ExchangeRateResponse":{"properties":{"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rate"},"rates":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Rates"}},"type":"object","title":"ExchangeRateResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LnurlAuthBody":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["data"],"title":"LnurlAuthBody"},"LnurlPayBody":{"properties":{"prepare_response":{"additionalProperties":true,"type":"object","title":"Prepare Response"}},"type":"object","required":["prepare_response"],"title":"LnurlPayBody"},"LnurlWithdrawBody":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"amount_msat":{"type":"integer","title":"Amount Msat"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"}},"type":"object","required":["data","amount_msat"],"title":"LnurlWithdrawBody"},"ParseInputBody":{"properties":{"input":{"type":"string","title":"Input"}},"type":"object","required":["input"],"title":"ParseInputBody"},"PaymentListResponse":{"properties":{"payments":{"items":{"$ref":"#/components/schemas/PaymentResponse"},"type":"array","title":"Payments"}},"type":"object","required":["payments"],"title":"PaymentListResponse"},"PaymentMethodEnum":{"type":"string","enum":["LIGHTNING","BITCOIN_ADDRESS","LIQUID_ADDRESS"],"title":"PaymentMethodEnum"},"PaymentResponse":{"properties":{"timestamp":{"type":"integer","title":"Timestamp"},"amount_sat":{"type":"integer","title":"Amount Sat","default":0},"fees_sat":{"type":"integer","title":"Fees Sat","default":0},"payment_type":{"type":"string","title":"Payment Type","default":"UNKNOWN"},"status":{"type":"string","title":"Status"},"details":{"additionalProperties":true,"type":"object","title":"Details","default":{}},"destination":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destination"},"tx_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tx Id"},"payment_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Hash"},"swap_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Swap Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},"type":"object","required":["timestamp","status"],"title":"PaymentResponse"},"PaymentStatusResponse":{"properties":{"status":{"type":"string","title":"Status"},"payment_details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Details"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"timestamp":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp"},"amount_sat":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount Sat"},"fees_sat":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fees Sat"}},"type":"object","required":["status"],"title":"PaymentStatusResponse"},"PrepareLnurlPayBody":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"amount_sat":{"type":"integer","title":"Amount Sat"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"validate_success_action_url":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Validate Success Action Url","default":true}},"type":"object","required":["data","amount_sat"],"title":"PrepareLnurlPayBody"},"ReceivePaymentBody":{"properties":{"amount":{"type":"integer","title":"Amount","description":"Amount in satoshis to receive"},"method":{"$ref":"#/components/schemas/PaymentMethodEnum","description":"Payment method","default":"LIGHTNING"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description for invoice"},"asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asset Id","description":"Asset ID for Liquid asset (optional)"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source of the payment request (e.g., 'woocommerce')"}},"type":"object","required":["amount"],"title":"ReceivePaymentBody"},"ReceiveResponse":{"properties":{"destination":{"type":"string","title":"Destination"},"fees_sat":{"type":"integer","title":"Fees Sat"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},"type":"object","required":["destination","fees_sat"],"title":"ReceiveResponse"},"SendOnchainBody":{"properties":{"address":{"type":"string","title":"Address","description":"Destination Bitcoin or Liquid address"},"amount_sat":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount Sat","description":"Amount in satoshis to send (ignored if drain)"},"drain":{"type":"boolean","title":"Drain","description":"Send all funds","default":false},"fee_rate_sat_per_vbyte":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fee Rate Sat Per Vbyte","description":"Custom fee rate (optional)"}},"type":"object","required":["address"],"title":"SendOnchainBody"},"SendOnchainResponse":{"properties":{"status":{"type":"string","title":"Status"},"address":{"type":"string","title":"Address"},"fees_sat":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fees Sat"}},"type":"object","required":["status","address"],"title":"SendOnchainResponse"},"SendPaymentBody":{"properties":{"destination":{"type":"string","title":"Destination","description":"Payment destination (invoice or address)"},"amount_sat":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount Sat","description":"Amount in satoshis to send (for Bitcoin)"},"amount_asset":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Asset","description":"Amount to send (for asset payments)"},"asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asset Id","description":"Asset ID for Liquid asset (optional)"},"drain":{"type":"boolean","title":"Drain","description":"Whether to drain the wallet","default":false}},"type":"object","required":["destination"],"title":"SendPaymentBody"},"SendResponse":{"properties":{"status":{"type":"string","title":"Status"},"destination":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destination"},"fees_sat":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fees Sat"},"payment_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Hash"},"swap_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Swap Id"}},"type":"object","required":["status"],"title":"SendResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}