This article describes the Xena Exchange dAcc REST API and the command line interface (CLI) that can be used instead of direct API calls.


Preparing dAccs

Trading with dAccs

Choosing between the REST API and CLI

Initialization and configuration

Node manipulation commands

Working with channels

Getting the list of Xena Exchange’s nodes

Creating a channel

Getting a list of active channels

Closing a channel

Sending funds

Getting a list of the latest payments

dAcc CLI notes

Error format

dAcc REST API

API authentication

RemoteNodes

Endpoint

Params

Response

IssueInvoices

Endpoint

Params

Response

RegisterNode

Endpoint

Params

Response

GetAccounts

Endpoint

Params

Response



The overview of dAccs and the installation of dAccs are described in dedicated articles.

The first version of dAccs is suited for clients that use automated trading software, although you are free to implement your own UI to send payments if needed.

Here are the main components of the setup:

Your local Lightning node (built from Xena Exchange’s fork of lnd), which stores the private keys of your wallet securely and is used to instantly fund your account.

  • The Lightning node requires a Bitcoin node, which doesn’t store any keys or Bitcoins and is used only for watching the blockchain. You can use the watcher node offered by Xena Exchange, your own Bitcoin node, or a third-party node (though the trird-party option is not recommended due to security and reliability reasons. If you decide to go with this option, make sure you trust your third-party provider).

    • The node built from Xena Exchange’s fork doesn’t use the main Lightning network and connects only to the Lightning nodes exposed by Xena Exchange.

  • The dAcc client is used for orchestration between your trading software, the Xena Exchange dAccs API, and your local Lightning node

    • Xena Exchange offers a dAcc CLI that implements all required flows and provides a simple-to-use interface. You are free to choose between it and your own custom implementation.

  • Xena Exchange’s Lightning and Bitcoin nodes are accessible only via VPN that must be configured on your server.


Preparing dAccs

  • Install and configure all components on your server

  • Initiate your Lightning node:

    • Create a new wallet or import an existing wallet (see Xena Exchange dAccs installation) to your local node

    • Deposit the funds you need for trading to this wallet

      • Note that this is your own wallet. Xena Exchange doesn’t have access to the funds stored in it.

      • You can use your Lightning wallet as a normal Bitcoin wallet.

  • Open a new channel and allocate some funds from your local Lightning wallet to it. These funds will be available to instantly fund your trading account on Xena Exchange through dAccs. Note that it’s not possible to change the allocation amount after the channel is opened.

    • Funds allocated to a channel are stored in a dedicated multi-sig wallet that requires signatures from both you and Xena Exchange to allow withdrawals (read more about the Lightning protocol here). Once a channel is opened, you can use your Bitcoins allocated to it to fund your account on Xena Exchange. Since the Lightning protocol works off-chain, the funding occurs almost instantly. Send additional funds to your Xena Exchange account when you need additional collateral there (such as when opening new positions or compensating a decreased margin level).

    • Opening a new channel is an on-chain operation and requires three to six confirmations (so expect it to take about one hour before the new channel is active). To save time, you can initiate the opening of a new channel immediately after one confirmation of the transaction you used to fund your Lightning wallet.

    • You can fund any of your Xena Exchange Accounts that support BTC — (i.e., spot accounts and margin accounts nominated in BTC—) through any of the active channels.

    • You can open as many channels as you need.

      • We recommend keeping at least two channels (on different Xena Exchange Lightning nodes) active for reliability.

  • Channels do not expire.

    • You can close your channels any time you like. Make sure there is enough collateral on your Xena Exchange account if you close a channel when some positions are open.

    • Xena Exchange has the right to close your channels if:

      • the remaining amount in the channel is less than 0.001 BTC

      • the amount used to fund your accounts via active channels exceeds XXX BTC

      • the channel has been inactive (i.e., your local Lightning node hasn’t connected to Xena Exchange’s nodes) for longer than XXX hours

  • When closing a channel, the funds that have been allocated to it but not yet used to fund your account are returned to your Lightning wallet. This is an on-chain transaction.

  • Channels are one-way. To withdraw your funds from Xena Exchange, use the standard withdrawal routines (Xena Exchange website or Transfers API). Withdrawals do not require closing your active channels.


Trading with dAccs

Once you have some channels up and running, you can start trading:

  1. Once your trading software decides that you need additional collateral on your Xena Exchange account, it asks the dAccs client to deposit the collateral.

  2. The client makes a call to the dAccs API to create a new invoice, passing the account to be funded and the channel to be used for the funding.

  3. The API returns the invoice.

  4. The retrieved invoice is passed to the local Lightning node to be paid using the specified channel.

  5. The node makes the payment (the redistribution of funds within the channel) almost instantaneously.

  6. The transferred funds are deposited to your account.

  7. A notification about the deposit and the new margin level is sent to your trading software via the Trading API.


Choosing between the REST API and CLI

The dAcc CLI (command line interface) encapsulates API specifics such as authentication and implements orchestration between the local client’s Lightning node and the dAcc API. There is no difference between the two approaches, but the pure API option requires more development on your end.

The dAcc CLI doesn’t have access to the keys of your Lightning node and cannot send payments without your command. The dAcc CLI is provided as an open-source application, so you can rest assured that there are no backdoors in it. It is distributed under the MIT license, so you can change it to better fit the specifics of your processes.


Initialization and configuration

  • Set up all required tools and create a new Lightning wallet (refer to this article).

  • Deposit some funds to the created wallet. These funds can later be used for funding channels or be withdrawn back to your main Bitcoin wallets. You can also use your Lightning wallet as a normal Bitcoin wallet.


Node manipulation commands

When implementing a custom dAccs client, refer to the Lightning API documentation.


Action

dAcc CLI command

dAcc CLI response

Comments

Unlock the node

daccs-cli node unlock --password=xY123z

No response if successful

You must unlock the node each time you restart it.

Get the status of the node

daccs-cli node status

{

    "identity_pubkey": "029f6e128469c0a8c91d8de8a77821fa

     99b5edd878bc2ea9e653af5222e8498a70",

    "alias": "XenaExchangeClient",

    "block_height": 1575116,

    "block_hash": "00000000e8ebf6db726791f6a41f545

          3a06daaee1e87aa17cb44e2b2a67c6c7e",

    "synced_to_chain": true,

    "testnet": false,

    "best_header_timestamp": 1566207353,

    "version": "0.6.1-beta commit=v0.6.1-beta",

    "chains": [

        {

            "chain": "bitcoin",

            "network": "testnet"

        }

    ]

}


Get a list of the node’s peers

daccs-cli node peers

[   

 "0395e0305ed4d3cacdc1c10bf5087e05674a38b2d90fad77f

    6280a5890e146314c@111.222.333.444:9735"

]


Disconnect the Lightning node from the remote nodes

daccs-cli node disconnect

No response if successful


Get the current available balance of the Lightning wallet

daccs-cli node balance

{

    "balance": "0.08760406"

}


Get the address of the wallet

daccs-cli node deposit

{

    "address": "tb1qn4jcade6wgxr0x3fs5n99u0h0h4s5ek604h7wr"

}


Use this address to fund your Lightning wallet


Working with channels

Getting the list of Xena Exchange’s nodes

We recommend you connect to at least two different Lightning nodes exposed by Xena Exchange for extra reliability.


dAccs CLI

Manual / dAcc API

daccs-cli api nodes

Response:

[

    {

        "id": "lnd1",

        "address": "021be96770857fa976faf573366ad6d

   85bee9554b9d00a0c79c78b6ad721a6c6eb@1.2.3.4"

    }

]

Use the RemoteNodes method


Creating a channel

We recommend you connect to at least two different Lightning nodes exposed by Xena Exchange for extra reliability.

Please keep in mind that due to the specifics of the Lightning protocol, a portion of the channel's capacity is not available for payments. The reserve that cannot be spent is about 2% of the capacity.


dAccs CLI

Manual / dAccs API

daccs-cli channel open --capacity=10.4 --node-id=lnd1

or

daccs-cli channel open --capacity 10.4 --node-pubkey=021be96770857fa976faf573366ad6d85b

      ee9554b9d00a0c79c78b6ad721a6c6eb

Response:

{

    "node": "021be96770857fa976faf573366ad6d8

    5bee9554b9d00a0c79c78b6ad721a6c6eb",

    "channel_point": "dc79a747296c0f46c634a79256e9f65e6

    30ae23706c1bf3d5135d03b0241991d:0",

    "status": "pending_open",

    "capacity": "10.4",

    "local_balance": "0",

    "remote_balance": "0"

}

  1. Register your Lightning node by passing the pubkey of your Lightning wallet to the RegisterNode method. The call to this method is idempotent (provided you send the same pubkey you used before), so you can safely register the same pubkey before opening each new channel. 

  2. Get a list of remote nodes and addresses by calling the RemoteNodes method.

  3. Make sure that your Lightning node is connected to at least one peer from the list of addresses.

  4. Open a new Lightning channel using the Lightning node API with the desired address.




Getting a list of active channels

dAccs CLI

Manual / dAcc API

daccs-cli channel list

Response:

[

    {

        "id": "1725837431424876545",

        "node": "0395e0305ed4d3cacdc1c10bf5087e05674a38b2d90fad77f6280a5890e146314c",

        "channel_point": "11c02ef547ed192fded77b0041bf53c8b3c92e080b7301d62316bf3bb144f51c:0",

        "status": "pending_open",

        "capacity": "0.02",

        "local_balance": "0.01999548",

        "remote_balance": "0"

    },

    {

        "node": "0395e0305ed4d3cacdc1c10bf5087e05674a38b2d90fad77f6280a5890e146314c",

        "channel_point": "eb1ec291e17efe863d78a205d366c26dea984527e83d1e1554fb5c4ae6119ebb:1",

        "status": "pending_open",

        "capacity": "0.02",

        "local_balance": "0.01999548",

        "remote_balance": "0"

    }

]

Use the Lightning node API to retrieve a list of channels.


Closing channel

dAccs CLI

Manual / dAcc API

daccs-cli channel close --id=1725837431424876545

or

daccs-cli channel close --channel-point=eb1ec291e17efe863d78a205d366c26d

   ea984527e83d1e1554fb5c4ae6119ebb:1

You must submit either the channel ID or channel point.

Response:

Empty if successful

Use the Lightning node API to close channels.


Sending funds

dAccs CLI

Manual / dAcc API

daccs-cli payment send --account=1234567890 --amount=0.25 --channel-id=1732331147103830017

or

daccs-cli payment send --account=1234567890 --amount=0.25 --channel-point=3cf91bb2d920074e9461127414c26

    ec4f6cbe1d8eec266a35885afd1f6a73140:1

Response: 

Empty if successful

  1. Create a new invoice using the IssueInvoices method, passing the channel point and account as arguments.

  2. Pass the invoice to your Lightning node and pay it.

Note, that the amount in the invoice issued by the API will be equal to 0. You can send any amount via Lightning using this invoice.


Getting a list of the latest payments

dAccs CLI

Manual / dAcc API

daccs-cli payment list

Response:

[

    {

        "node": "0395e0305ed4d3cacdc1c10bf5087

             e05674a38b2d90fad77f6280a5890e146314c",

        "timestamp": "2019-08-15T16:37:31+03:00",

        "amount": "0.01"

    },

    {

        "node": "0395e0305ed4d3cacdc1c10bf5087

              e05674a38b2d90fad77f6280a5890e146314c",

        "timestamp": "2019-08-15T13:12:34+03:00",

        "amount": "0.03"

    },

    {

         "node": "0395e0305ed4d3cacdc1c10bf5087

          e05674a38b2d90fad77f6280a5890e146314c",

        "timestamp": "2019-08-15T13:12:12+03:00",

        "amount": "0.002"

    }

]

Use the Lightning node API to retrieve a list of payments.



dAcc CLI notes

The CLI is a golang program that can be built and launched on any platform. It is distributed as an open-source product (https://github.com/xenaex/daccs-cli) under the MIT license. Feel free to modify it to implement the specifics of your trading flow. The binaries for different platforms can be downloaded here.

After setting the CLI up, run “./daccs-cli help” to get help.

A call to each method results in the CLI writing a JSON with data or an error message to stdout or stderr.

Global arguments such as API Secret can be passed as arguments (e.g., “daccs-cli channel open --api-key=12345”) to calls or environment variables (“$XENA_DACCS_API_KEY”). Here are the global arguments:

--api-url

$XENA_DACCS_API_URL

Optional; use only if you need to connect to a non-production API instance (https://api.xena.exchange/daccs/)

--api-key

$XENA_DACCS_API_KEY

API key of your key with the scope of the dAccs

--api-secret

$XENA_DACCS_API_SECRET

API secret of your key with the scope of the dAccs

--lnd-host

$XENA_DACCS_LND_HOST

The IP of your local Lightning node RPC (see "running the node" in the article describing installation)

--lnd-macaroon

$XENA_DACCS_LND_MACAROON

The path to the Macaroon file created by your local Lightning node (see "running the node" in the article describing installation)

--lnd-tls-cert

$XENA_DACCS_LND_TLS

The path to the TLS certificate created by your local Lightning node (see "running the node" in the article describing installation)


Error format

{

    “error”: “<Error description>”

}


dAcc REST API

API authentication

You must use an API key with the scope “dAccs” to use the API and CLI. Learn how to obtain an API key.

Each call to the REST dAccs API must contain the usual authentication headers (refer to this article).


RemoteNodes

Used to retrieve information about Xena Exchange’s Lightning nodes.


Endpoint


GET https://api.xena.exchange/daccs/nodes


Params


None


Response


[

    {

        "id":"lnd1",

        "address":"039529ef2d493689a6e4abfab27fcc12550

            0c3468ab335be95c247259899061be1@10.130.0.4"

    },

    ...

]


IssueInvoices

Returns the invoice object that must be passed to the Lightning node and paid to fund your account on the exchange.


Endpoint


POST https://api.xena.exchange/daccs/accounts/<accountId>/invoices


Params


{

    “externalID”: “32463285632852”,

    “chanPoints”: [

        “3cf91bb2d920074e9461127414c26ec4f6

            cbe1d8eec266a35885afd1f6a73140:1”

    ]   

}

External ID is a unique ID that you can use for de-duplication on your side.


Response


[

    {

        "nodeId": "lnd1",

        "paymentRequest": "PLACE HERE",

        “chanPoint”: “3cf91bb2d920074e9461127414c26ec

            4f6cbe1d8eec266a35885afd1f6a73140:1”,

        “amount”: 0

    }

]


RegisterNode

Registers the pubkey of your Lightning wallet. The call to this method is idempotent (provided you are sending the same pubkey as earlier), so you can safely register the same pubkey before opening each new channel. If you send another pubkey, it will be registered as well.


Endpoint


POST https://api.xena.exchange/daccs/pubkey


Params


{

    “pubkey”: “<Address (pubkey) of your Lightning wallet>”

}


Response

{

    "id": 8,

    "pubKey": "029f6e128469c0a8c91d8de8a77821

        fa99b5edd878bc2ea9e653af5222e8498a70",

    "exists": false

}


GetAccounts

Returns a list of all your accounts on Xena Exchange that can be funded using dAccs.


Endpoint


GET https://api.xena.exchange/daccs/accounts


Params


None


Response

[

     { "accountId": 82637486 },

     { "accountId": 1012833765 },

    ...

]


Limits

Returns current restrictions to be adhered to when using dAccs.


Endpoint


GET https://api.xena.exchange/daccs/limits


Params


None


Response

{

    "minChannelCapacity": "0.01",

    "minPaymentAmount": "0.00006",

    "channelReserveMultiplier": "2"

}