Using Flow API

Search…
Using Flow API
This page describes how to use Flow and manage your orders
To use Flow you must have Pool installed on your node first! Pool is required to claim a sidecar ticket and faciliate the channel openings with the Pool Auction server. Learn how to install Pool here. Although you must have Pool installed, you do not need to have a Pool account created.
Lifecycle
When purchasing channels with Flow, the orders go through a fairly straightforward lifecycle. This lifecycle is outlined here to help you better understand how this works.
1.Get a quote for how much a given channel size will cost.
2.Create an order with the given channel size.
3.Pay the amount that's due for the channel either in onchain or Lightning Bitcoin.
4.Once a payment is detected, Flow will automatically create a sidecar ticket.
5.Take this sidecar ticket and register it with your node's Pool daemon either on command line or through Lightning Terminal.
6.Wait for the order to be matched (this can take a while in some cases).
7. Boom. Channel opened to your node.
To redeem a Sidecar Ticket generated from pool, you must have installed poold version v0.5.1-alpha or later OR Lightning Terminal v0.5.2-alpha or later.
Creating Orders
The first thing we recommend doing before actually creating an order is getting a quote so you know exactly how much it's going to cost. You can do that with the /flow/quote endpoint. In our example we'll be purchasing a 2,000,000 satoshi inbound channel.
Get a quote
$ curl -H "X-VOLTAGE-AUTH: vYOURAPIKEY" \
    -H "Content-Type: application/json" \
    -X POST -d '{"capacity": 2000000}' \
    https://api.voltage.cloud/flow/quote
    
{
  "voltage_fee": 760,
  "pool_fee": 26050,
  "self_chan_balance_fee": 0,
  "total_fee": 26810,
  "amount_due": 26810,
  "capacity": 2000000,
  "self_chan_balance": 0,
  "lease_duration_blocks": 2016,
  "rate_fixed": 12922,
  "rate_bps": 1735,
  "credit_used": 0
}
This tells us that the total amount we'll pay for a 2 million satoshi channel for 2016 blocks (about 2 weeks) is 26810 sats. This sounds good so we can use the same payload to actually create the order with the /flow/create endpoint.
Create the order
$ curl -H "X-VOLTAGE-AUTH: vYOURAPIKEY" \
    -H "Content-Type: application/json" \
    -X POST -d '{"capacity": 2000000}' \
    https://api.voltage.cloud/flow/create
    
{
  "order_id": "a03ce60f-7a67-4f5f-8fa1-f2db749cde43FO",
  "creation_date": "2021-10-13T04:01:46Z",
  "status": "waiting_payment",
  "paid": false,
  "order_nonce": "",
  "capacity": 2000000,
  "self_chan_balance": 0,
  "lease_duration_blocks": 2016,
  "node_tier": "best",
  "rate_fixed": 12922,
  "sidecar_ticket": "",
  "onchain_address": "tb1qlk4f5q6sqy2wu47wst7xvslwhv5emnhnzdvkle",
  "lightning_invoice": "lntb268100n1pskvk3tpp5u6n3ufq4f3088fnrm52mqcum8sw4a2kv5ufqpcm9xn6rl2t9plrsdr52pskjepqw3hjqarkdak8gct8v5szsnmjv3jhygzfgsazqenvdamj7cfsxd3k2d3svcknwcfkxuknge34vcknsenpxykkvvnyvgmngwtrv3jngv6xfu5scqzpgxqrrsssp57x3s3qsksvwz0yrarnygnxms4yn7aae6gjk8t5c9g3jyprhheyhq9qyyssqeyqys6gwfrst9ha7h77qlp75mygpv2el54l9q56jg3wxamsehxeqn2e5r6ezucuujp7hpzp06pe0umxlrdvy0nnesvhwdxldur4t0asqz2u7uf",
  "voltage_fee": 760,
  "pool_fee": 26050,
  "self_chan_balance_fee": 0,
  "total_fee": 26810,
  "amount_due": 26810,
  "credit_used": 0
}
Now we have a real order opened in Flow. Its status should be waiting_payment which means it's waiting for you to pay the fee to open the channel. We can cover this next!
Note: if you hold a Corporate Account for Flow you don't have to pay this amount. Your order automatically creates a sidecar ticket and the fee is added to your account.
Paying for Orders
Now that we have an order placed we need to pay it so the Flow system can create a sidecar ticket for the order. When you create your order, the response has two fields for payment. onchain_address and lightning_invoice. You can find how much you owe in the amount_due field of the create API. You must either pay the amount due to the onchain Bitcoin address or the Lightning invoice. As soon as we detect the payment, we automatically create a sidecar ticket for the order. If you have credit available in your account, either from cancelling previously paid orders, or from redeeming a coupon, we will first deduct from your credit. If your credit covers the entire order, we will not generate a BTCPay Invoice, and just provide you with a sidecar ticket to register.
Note: services like Strike or River make paying these invoices with fiat really easy
Finding Order Status
After you have paid for your invoice, you'll want to check the order's status to know when it creates the sidecar ticket. You can use the /flow/status endpoint for this. Once the order's status switches to created, that means that it successfully create a sidecar ticket and you can now claim it. You will see that the sidecar_ticket field now has a value that contains a ticket.
$ curl -H "X-VOLTAGE-AUTH: vYOURAPIKEY" \
    -H "Content-Type: application/json" \
    -X POST -d '{"order_id": "a03ce60f-7a67-4f5f-8fa1-f2db749cde43FO"}' \
    https://api.voltage.cloud/flow/status
    
{
  "order_id": "a03ce60f-7a67-4f5f-8fa1-f2db749cde43FO",
  "creation_date": "2021-10-13T04:01:46Z",
  "status": "created",
  "paid": true,
  "order_nonce": "",
  "capacity": 2000000,
  "self_chan_balance": 0,
  "lease_duration_blocks": 2016,
  "node_tier": "best",
  "rate_fixed": 12922,
  "sidecar_ticket": "sidecar15oL8PjQ8hJKsErEfuxik9FeSEfKA5SasFMiqXqcXKCTFHGaqHPuQmAMmif4rrJKWgbE2Lc4HEDzo3WpRjwPMktxZEVYneWkFztyCEoRnvGrbvpRPSru8rLn5huKAvWjcLYEpXuetfV8tS9HhRQBZaptk415GrX2HbkP7wSnQQReuJYoyiirDvATkTHgBkYkXrgg4284Ce4KunRjrPsQTp8tKK4pL2fkwQtk8bBh8gxYT64LQ",
  "onchain_address": "tb1qlk4f5q6sqy2wu47wst7xvslwhv5emnhnzdvkle",
  "lightning_invoice": "lntb268100n1pskvk3tpp5u6n3ufq4f3088fnrm52mqcum8sw4a2kv5ufqpcm9xn6rl2t9plrsdr52pskjepqw3hjqarkdak8gct8v5szsnmjv3jhygzfgsazqenvdamj7cfsxd3k2d3svcknwcfkxuknge34vcknsenpxykkvvnyvgmngwtrv3jngv6xfu5scqzpgxqrrsssp57x3s3qsksvwz0yrarnygnxms4yn7aae6gjk8t5c9g3jyprhheyhq9qyyssqeyqys6gwfrst9ha7h77qlp75mygpv2el54l9q56jg3wxamsehxeqn2e5r6ezucuujp7hpzp06pe0umxlrdvy0nnesvhwdxldur4t0asqz2u7uf",
  "voltage_fee": 760,
  "pool_fee": 26050,
  "self_chan_balance_fee": 0,
  "total_fee": 26810,
  "amount_due": 26810,
  "credit_used": 0
}
Claiming an Order
Now we have a sidecar ticket that's redeemable for the values we requested. Sweet! Now we just have to claim the ticket with the Pool daemon that's running on our node. We can do this from the Pool CLI or via the Lightning Terminal's UI. Here's what we'd run on the CLI:
pool sidecar register sidecar15oL8PjQ8hJKsErEfuxik9FeSEfKA5SasFMiqXqcXKCTFHGaqHPuQmAMmif4rrJKWgbE2Lc4HEDzo3WpRjwPMktxZEVYneWkFztyCEoRnvGrbvpRPSru8rLn5huKAvWjcLYEpXuetfV8tS9HhRQBZaptk415GrX2HbkP7wSnQQReuJYoyiirDvATkTHgBkYkXrgg4284Ce4KunRjrPsQTp8tKK4pL2fkwQtk8bBh8gxYT64LQ
Boom. That's all you have to do to claim the ticket. Now that you've claimed the ticket, you have to wait for a match to happen in the Pool Auction server. This can take a few minutes to a few hours. To confirm that our Pool server received the ticket you can check it's status again. Once we detect the ticket the order will transition to submitted.
The below image shows where in the Lighting Terminal UI you can register the sidecar channel. If this button isn't available, you might need to update your Lightning Terminal version.
Select Register Sidecar Channel
Cancelling an Order
If you would like cancel an order, it's really easy. Simply make a request to the /flow/cancel endpoint with your Order ID. 
$ curl -H "X: vYOURAPIKEY" \
    -H "Content-Type: application/json" \
    -X POST -d '{"order_id": "a03ce60f-7a67-4f5f-8fa1-f2db749cde43FO"}' \
    https://api.voltage.cloud/flow/cancel
    
{
  "order_id": "a03ce60f-7a67-4f5f-8fa1-f2db749cde43FO",
  "creation_date": "2021-10-13T04:01:46Z",
  "status": "cancelled",
  "paid": true,
  "order_nonce": "",
  "capacity": 2000000,
  "self_chan_balance": 0,
  "lease_duration_blocks": 2016,
  "node_tier": "best",
  "rate_fixed": 12922,
  "sidecar_ticket": "sidecar15oL8PjQ8hJKsErEfuxik9FeSEfKA5SasFMiqXqcXKCTFHGaqHPuQmAMmif4rrJKWgbE2Lc4HEDzo3WpRjwPMktxZEVYneWkFztyCEoRnvGrbvpRPSru8rLn5huKAvWjcLYEpXuetfV8tS9HhRQBZaptk415GrX2HbkP7wSnQQReuJYoyiirDvATkTHgBkYkXrgg4284Ce4KunRjrPsQTp8tKK4pL2fkwQtk8bBh8gxYT64LQ",
  "onchain_address": "tb1qlk4f5q6sqy2wu47wst7xvslwhv5emnhnzdvkle",
  "lightning_invoice": "lntb268100n1pskvk3tpp5u6n3ufq4f3088fnrm52mqcum8sw4a2kv5ufqpcm9xn6rl2t9plrsdr52pskjepqw3hjqarkdak8gct8v5szsnmjv3jhygzfgsazqenvdamj7cfsxd3k2d3svcknwcfkxuknge34vcknsenpxykkvvnyvgmngwtrv3jngv6xfu5scqzpgxqrrsssp57x3s3qsksvwz0yrarnygnxms4yn7aae6gjk8t5c9g3jyprhheyhq9qyyssqeyqys6gwfrst9ha7h77qlp75mygpv2el54l9q56jg3wxamsehxeqn2e5r6ezucuujp7hpzp06pe0umxlrdvy0nnesvhwdxldur4t0asqz2u7uf",
  "voltage_fee": 760,
  "pool_fee": 26050,
  "self_chan_balance_fee": 0,
  "total_fee": 26810,
  "amount_due": 26810,
  "credit_refund": 26810
}
You should notice a new field called credit_refund. If you paid the fees on your order before cancelling, this amount will be added to your user account, and will be good for the same amount as your fees. This allows you to easily reuse the fees you paid on a new order. If you'd like the fees paid back to you instead of the coupon please contact us.
Viewing Coupons
You can view all of your coupons with the /flow/coupons endpoint. This will show you all used and unused coupons, their amount in satoshis, and whether the coupon has been claimed or not.
$ curl -H "X-VOLTAGE-AUTH: vYOURAPIKEY" \
    -X GET \
    https://api.voltage.cloud/flow/coupons
    
{
  "coupons": [
    {
      "amount": 2230,
      "order_id": "18a80b8d-026e-4ad0-9a96-7f09d46b1dbaFC",
      "claimed" True
    },
    {
      "amount": 5000,
      "order_id": "8675abcd-026e-4ad0-9a96-7f09d46b1dbdFC",
      "claimed" False
    }
  ]
}
To use a coupon, use the the /flow/redeem endpoint which is documented below. 
Redeeming Coupons
When a coupon is redeemed its value will be added to your user account Flow credit. Your Flow credit will be used first when creating new channels, and when using the /flow/quote endpoint, the API will respond with how much a channel will cost, with your available credit applied.
$ curl -H "X: vYOURAPIKEY" \
    -H "Content-Type: application/json" \
    -X POST -d '{"coupon": "a03ce60f-7a67-4f5f-8fa1-f2db749cde43FC"}' \
    https://api.voltage.cloud/flow/cancel
    
{
    "coupon": "268dc527-abd7-406b-a043-c4baa647088fFC",
    "credit": 3735,
    "coupon_amount": 2000
}
Order Statuses
waiting_payment: Order was created and it's waiting for the invoice to be paid
expired: Invoice was not paid before the end expiration time
creating: Creating the sidecar ticket
created: The sidecar ticket was created
submitted: The sidecar ticket was registered with a node and submitted to Pool.
filled: The order got filled in the pool order book.
failed: something went wrong in the creation process
Flow - Previous
Interacting with Flow
Next - Flow
Corporate Accounts
Last modified 9mo ago
Copy link
Outline
Lifecycle
Creating Orders
Paying for Orders
Finding Order Status
Claiming an Order
Cancelling an Order
Viewing Coupons
Redeeming Coupons
Order Statuses