LightningHub API documentation version v1

http://api.bluewallet.io/{version}

version: required(v1)

Home

Welcome to the LightningHub API Documentation. The LightningHub API allows you to connect your Bitcoin/Lightning Bluewallet App and serve multiple user accounts via a shared Lightning Node.

Most of the API requests require authentication. This is done via a request header named Authorization: containing an access token, which has to be send along with every request. To obtain an access token, the following steps have to be performed:

Create an account via the /create resource.
Create an access token via the /auth resource using the credentials (login/password) returned in step 1.
Provide the access token returned in step 2 as the value of the Authorization header in every following request.

Error codes

This API returns errors as a JSON object in the following format:

{
   "error": true,
   "code": <INTEGER>,
   "message": "<DESCRIPTION>",
}

The following error codes are defined:

1 : bad authentication
2 : not enough balance
4 : not a valid invoice
6 : server fault
7 : Lightning node failure
8 : bad arguments
9 : payment in transit
10 : payment failed

Lighting Node Info

Get status information about the connected Lightning node.

Create new account

Create a new custody account on the LightningHub. Each account has it's own spendable balance which is managed via an internal ledger (database).

/create post

post

Send account creation request

Request
Response

Body

Media type: application/json

Type: object

Properties

partnerid: required(string - pattern: ^bluewallet$)
accounttype: required(one of common, test)

Example:

{
  "partnerid": "bluewallet",
  "accounttype": "common"
}

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

login: required(string - pattern: ^[0-9|a-f]+$)
password: required(string - pattern: ^[0-9|a-f]+$)

Example:

{
  "login": "04f8996da763b7a969b1",
  "password": "5e884898da28047151d0"
}

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Get access token

Create an access token using your account credentials (login/password), which is needed for most of the API calls.

/auth post

post

Send user authentication request

Request
Response

Body

Media type: application/json

Type: object

Properties

login: required(string - pattern: ^[0-9|a-f]+$)
password: required(string - pattern: ^[0-9|a-f]+$)
refresh_token: (string - pattern: ^[0-9|a-f]+$)

Example:

{
  "login": "04f8996da763b7a969b1",
  "password": "5e884898da28047151d0"
}

HTTP status code 200

Successful user authentication response which provides an access token that needs to be send along with all requests that require authentication.

Body

Media type: application/json

Type: object

Properties

access_token: required(string - pattern: ^[0-9|a-f]+$)
refresh_token: required(string - pattern: ^[0-9|a-f]+$)

Example:

{
  "access_token": "bf3771fdebf08fd83a3b4cbe2f0aa3ef4cf957b3",
  "refresh_token": "f77a47bb198f496c5cb03cf06ac544a6e194637d"
}

HTTP status code 401

Failed user authentication response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Show Account Balance

Show spendable custody account balance of the authenticated user.

/balance get

get

Send balance information request

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Response
Security

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

BTC: required(object)
- AvailableBalance: required(integer - minimum: 0)

Example:

{
  "BTC": {
    "AvailableBalance": 0
  }
}

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Show Funding Address

Get an on-chain bitcoin deposit address for the authenticated user. Deposits will be credited to the user's custody account balance.

/getbtc get

get

Send deposit address request

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Response
Security

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: BTCAddressItem

address: required(string - pattern: ^(bc|tb)1[ac-hj-np-z02-9]{6,}$)

Example:

[
  {
    "address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx"
  }
]

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Show Pending Deposits

Show on-chain funding transactions with less than 3 confirmations for the authenticated user's account. Deposits will only be credited to the user's spendable account balance after the funding transaction received 3 confirmations.

/getpending get

get

Get a list of pending deposits along with their details for the authenticated user's custody account.

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Response
Security

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: BTCTransaction

amount: required(number)
account: required(string)
address: required(union of base-types.Base58Address or base-types.Bech32Address)
category: required(string)
confirmations: required(integer - minimum: 0)
blockhash: required(string - pattern: ^[0-9|a-f]+$)
blockindex: required(integer - minimum: 0)
blocktime: required(integer - minimum: 0)
txid: required(string - pattern: ^[0-9|a-f]+$)
walletconflicts: required(any)
time: required(integer - minimum: 0)
timereceived: required(integer - minimum: 0)

Example:

[
  {
    "amount": 0.00078061,
    "account": "521172",
    "address": "3F9seBGCJZQ4WJJHwGhrxeGXCGbrm5SNpF",
    "category": "receive",
    "confirmations": 1,
    "blockhash": "0000000000000000000edf18e9ece18e449c6d8eed1f729946b3531c32ee9f57",
    "blockindex": 693,
    "blocktime": 1535024914,
    "txid": "28a74277e47c2d772ee8a40464209c90dce084f3b5de38a2f41b14c79e3bfc62",
    "walletconflicts": [],
    "time": 1535024434,
    "timereceived": 1535024434
  }
]

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Create Lightning invoice

Create BOLT-11 compatible Lightning invoices

/addinvoice post

post

Request a BOLT-11 compatible Lightning invoice that can be paid by any other BOLT-11 compatible wallet. If the invoice is paid the respective amount will be credited to the authenticated user who created it.

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Body

Media type: application/json

Type: object

Properties

amt: required(integer - minimum: 0)
Requested amount in milli-satoshi (msat)
memo: (string)
Optional, short description of purpose of payment, to attach along with the invoice. Used for record keeping purposes for the invoice's creator, and will also be set in the description field of the encoded payment request if the description_hash field is not being used.
Annotations
- annotation-types.questionable
```
"For a custody lightning wallet this could leak potentially\nsensitive, private information to the operator of the service.\nBluewallet client implementations should at least inform their users\nabout this issue.\n"
```

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

payment_request: required(string - pattern: ^ln(bc|tb)[1-9][0-9]*[munp]1[ac-hj-np-z02-9]{6,}$)
bech32 encoded bitcoin payment request according to the BOLT-11 specification.
r_hash: required(object)
The payment hash of the invoice. For lookup purposes.
Annotations
- annotation-types.questionable
```
"This property is an implementation detail of the LND rpc api.\nWhy as a buffer representation? Wouldn't a hexadecimal string be\nsufficient?\n"
```
- type: required(string - pattern: ^Buffer$)
- data: required(array of integer)
add_index: required(integer)
The "add" index of this invoice. Each newly created invoice will increment this index making it monotonically increasing. Callers to the SubscribeInvoices call can use this to instantly get notified of all added invoices with an add_index greater than this one.
Annotations
- annotation-types.questionable
```
"This property is an implementation detail of the LND rpc api.\nWhy is it exposed to Bluewallet clients? It's potentially\nsensitive information that is leaked.\n"
```
pay_req: required(string - pattern: ^ln(bc|tb)[1-9][0-9]*[munp]1[ac-hj-np-z02-9]{6,}$)
Same as payment_request. Still here for client backwards compatibility.
Annotations
- annotation-types.deprecated

Example:

{
  "payment_request": "lnbc10u1pwenn70pp5c25zh2denvxvthesgtt6kphgudck95v7xewnf2tmyujp50d0svksdqqcqzpgcale3550tlvx75pjj59rtg6lukvs52s2al7v0xnmry9399eqe03sx3nlp9758al5l7j6xrzlr49q2c9cux4gl7fart2j9ammfp4f26cqxtyghg",
  "add_index": 104719,
  "r_hash": {
    "type": "Buffer",
    "data": [
      194,
      168,
      43,
      169,
      185,
      155,
      12,
      197,
      223,
      48,
      66,
      215,
      171,
      6,
      232,
      227,
      113,
      98,
      209,
      158,
      54,
      93,
      52,
      123,
      39,
      36,
      26,
      61,
      175,
      131,
      45
    ]
  },
  "pay_req": "lnbc10u1pwenn70pp5c25zh2denvxvthesgtt6kphgudck95v7xewnf2tmyujp50d0svksdqqcqzpgcale3550tlvx75pjj59rtg6lukvs52s2al7v0xnmry9399eqe03sx3nlp9758al5l7j6xrzlr49q2c9cux4gl7fart2j9ammfp4f26cqxtyghg"
}

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Pay Lightning invoices

Pay BOLT-11 compatible Lightning invoices

/payinvoice post

post

Request a BOLT-11 compatible Lightning invoice to be paid by the custodian. If the payment is successful, the respective amount + a fee is substracted from the authenticated user's balance.

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Body

Media type: application/json

Type: object

Properties

invoice: required(string - pattern: ^ln(bc|tb)[1-9][0-9]*[munp]1[ac-hj-np-z02-9]{6,}$)
bech32 encoded bitcoin payment request according to the BOLT-11 specification.
amount: (integer - minimum: 1)
For so called tip invoices only: The amount the payer wants to tip.

HTTP status code 200

There doesn't seem to be a strict response schema for this method. Depending on wheter it was an internal payment or a real Lightning network payment, different response bodies are returned by the current implementation. Anyway, current client implementation doesn't seem to use any of the data provided in the response body.

Body

Media type: application/json

Type: object | bluewallet-types.LNDSendResponse | bluewallet-types.LNDPayReq

HTTP status code 400

Body

Media type: application/json

Type: any

Example:

{
  error: true,
  code: 4,
  message: 'not a valid invoice',
}

HTTP status code 403

Body

Media type: application/json

Type: any

Example:

{
  error: true
  code: 2
  message: not enough balance. Make sure you have at least 1% reserved for potential fees
}

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

HTTP status code 500

Body

Media type: application/json

Type: any

Example:

{
  error: true,
  code: 6,
  message: 'Server fault',
}

HTTP status code 502

Body

Media type: application/json

Type: any

Example:

{
  error: true,
  code: 10,
  message: 'Payment failed. Does the receiver have enough inbound capacity?',
}

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Show Transaction History

Show the transaction history of authenticated user's account.

/gettxs get

get

Get a list of transactions (deposits and payments) along with their details for the authenticated user's custody account.

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Query Parameters

limit: (integer - default: 10 - minimum: 0)
offset: (integer - default: 0 - minimum: 0)

HTTP status code 200

Body

Media type: application/json

Type: array of (bluewallet-types.BTCTransaction | bluewallet-types.Payment)

Example:

[
  {
    "amount": 0.00078061,
    "account": "521172",
    "address": "3F9seBGCJZQ4WJJHwGhrxeGXCGbrm5SNpF",
    "category": "receive",
    "confirmations": 5,
    "blockhash": "0000000000000000000edf18e9ece18e449c6d8eed1f729946b3531c32ee9f57",
    "blockindex": 693,
    "blocktime": 1535024914,
    "txid": "28a74277e47c2d772ee8a40464209c90dce084f3b5de38a2f41b14c79e3bfc62",
    "walletconflicts": [],
    "time": 1535024434,
    "timereceived": 1535024434
  },
  {
    "timestamp": 1535054434,
    "type": "paid_invoice",
    "value": 12,
    "fee": 0,
    "memo": "tip"
  }
]

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Show Invoices

Show Lightning invoices created by the authenticated user.

/getuserinvoices get

get

Get a list of Lightning invoices along with their payment status details for the authenticated user's custody account.

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Query Parameters

limit: (integer - default: 10 - minimum: 0)
offset: (integer - default: 0 - minimum: 0)

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: Invoice

timestamp: required(integer)
type: required(user_invoice)
amt: required(integer)
description: required(string)
ispaid: required(boolean)
expire_time: required(integer)
payment_hash: required(string - pattern: ^[0-9|a-f]+$)
payment_request: required(string - pattern: ^ln(bc|tb)[1-9][0-9]*[munp]1[ac-hj-np-z02-9]{6,}$)
bech32 encoded bitcoin payment request according to the BOLT-11 specification.
r_hash: required(object)
The payment hash of the invoice. For lookup purposes.
Annotations
- annotation-types.questionable
```
"This property is an implementation detail of the LND rpc api.\nWhy as a buffer representation? Wouldn't a hexadecimal string be\nsufficient?\n"
```
- type: required(string - pattern: ^Buffer$)
- data: required(array of integer)
add_index: required(integer)
The "add" index of this invoice. Each newly created invoice will increment this index making it monotonically increasing. Callers to the SubscribeInvoices call can use this to instantly get notified of all added invoices with an add_index greater than this one.
Annotations
- annotation-types.questionable
```
"This property is an implementation detail of the LND rpc api.\nWhy is it exposed to Bluewallet clients? It's potentially\nsensitive information that is leaked.\n"
```
pay_req: required(string - pattern: ^ln(bc|tb)[1-9][0-9]*[munp]1[ac-hj-np-z02-9]{6,}$)
Same as payment_request. Still here for client backwards compatibility.
Annotations
- annotation-types.deprecated

Example:

[
  {
    "timestamp": 1535054434,
    "type": "user_invoice",
    "amt": 12,
    "description": "tip",
    "ispaid": true,
    "expire_time": 3600,
    "payment_hash": "18cfd986f49569a3276624dbc02bdc7fdfa57053f9dd0d4e7fa5902e9c926de5",
    "payment_request": "lnbc10u1pwenn70pp5c25zh2denvxvthesgtt6kphgudck95v7xewnf2tmyujp50d0svksdqqcqzpgcale3550tlvx75pjj59rtg6lukvs52s2al7v0xnmry9399eqe03sx3nlp9758al5l7j6xrzlr49q2c9cux4gl7fart2j9ammfp4f26cqxtyghg",
    "add_index": 104719,
    "r_hash": {
      "type": "Buffer",
      "data": [
        194,
        168,
        43,
        169,
        185,
        155,
        12,
        197,
        223,
        48,
        66,
        215,
        171,
        6,
        232,
        227,
        113,
        98,
        209,
        158,
        54,
        93,
        52,
        123,
        39,
        36,
        26,
        61,
        175,
        131,
        45
      ]
    },
    "pay_req": "lnbc10u1pwenn70pp5c25zh2denvxvthesgtt6kphgudck95v7xewnf2tmyujp50d0svksdqqcqzpgcale3550tlvx75pjj59rtg6lukvs52s2al7v0xnmry9399eqe03sx3nlp9758al5l7j6xrzlr49q2c9cux4gl7fart2j9ammfp4f26cqxtyghg"
  }
]

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

Decode Lightning Invoice

Decode a Lightning invoice into a human readable format.

/decodeinvoice get

get

Decode a BOLT-11 compatible Lightning invoice into a human readable format. Uses the implementation of the connected Lightning node so the client app doesn't have to implement this.

Secured by Access Token (Pass Through)

This API supports Pass Through Authentication via the Authorization header.

Query Parameters

invoice: required(string - pattern: ^ln(bc|tb)[1-9][0-9]*[munp]1[ac-hj-np-z02-9]{6,}$)
bech32 encoded bitcoin payment request according to the BOLT-11 specification.

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

destination: required(string)
payment_hash: required(string - pattern: ^[0-9|a-f]+$)
num_satoshis: required(integer)
timestamp: required(integer)
expiry: required(integer)
description: required(string)
description_hash: required(string - pattern: ^[0-9|a-f]+$)
fallback_addr: required(string)
cltv_expiry: required(integer)
route_hints: (any)

HTTP status code 400

Returned if the invoice query parameter didn't provide a valid invoice in the BOLT-11 format.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 4,
  "message": "not a valid invoice"
}

HTTP status code 429

Error response when the rate limit of requests was reached.

Headers

X-Ratelimit-Limit: required(integer)
The request limit per time window
X-Ratelimit-Remaining: required(integer)
The number of requests left for the time window
X-Ratelimit-Reset: required(integer)
The remaining window before the rate limit resets in UTC epoch seconds

Body

Media type: application/json

Type: string

Example:

Too many requests, please try again later.

Secured by Access Token (Pass Through)

Headers

Authorization: required(string - pattern: ^[0-9|a-f]+$)
The access_token obtained via the /auth request

HTTP status code 401

Error response when wrong credentials where provided.

Body

Media type: application/json

Type: object

Properties

error: required(boolean)
code: required(integer - minimum: 0)
message: required(string)

Example:

{
  "error": true,
  "code": 1,
  "message": "bad auth"
}

LightningHub API documentation version v1

Lighting Node Info

get /getinfo

HTTP status code 200

Body

Create new account

post /create

Body

HTTP status code 200

Body

HTTP status code 429

Headers

Body

Get access token

post /auth

Body

HTTP status code 200

Body

HTTP status code 401

Body

HTTP status code 429

Headers

Body

Show Account Balance

get /balance

HTTP status code 200

Body

HTTP status code 429

Headers

Body

Secured by Access Token (Pass Through)

Headers

HTTP status code 401

Body

Show Funding Address

get /getbtc

HTTP status code 200

Body

Secured by Access Token (Pass Through)

Headers

HTTP status code 401

Body

Show Pending Deposits

get /getpending

HTTP status code 200

Body

HTTP status code 429

Headers

Body

Secured by Access Token (Pass Through)

Headers

HTTP status code 401

Body

Create Lightning invoice

post /addinvoice

Body

Annotations

HTTP status code 200

Body

Annotations

Annotations

Annotations

HTTP status code 429

Headers

Body

Secured by Access Token (Pass Through)

Headers

HTTP status code 401

Body

Pay Lightning invoices

post /payinvoice

Body

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 403

Body

HTTP status code 429

Headers