Friday 1 August 2014

Setting up a Stellar trust line

Recently Stellar, a decentralized protocol for sending and receiving money in any pair of currencies, was announced. I decided to have a play around (because why not?). A core concept to Stellar is that of a gateway; an individual or organisation that takes a deposit (in 'real' currency) and credits you on the network.

Coinex are a New Zealand-based gateway, and are the first gateway for Stellar; they put up a challenge to be the first person to use them as a gateway (which I won!). To do this, you have to say that you trust that gateway to hold a particular amount of currency; in this case I wanted to publish the fact that I trust Coinex to hold up to $20 NZD for me.

To do this, you'll need to interact directly with the API (Stellar clients are still playing catch-up), and submit the following JSON:
    "method": "submit",
    "params": [
            "secret": "<SECRET>",
            "tx_json": {
                "TransactionType": "TrustSet",
                "Account": "<your Stellar address>",
                "LimitAmount": {
                    "value": "<the amount you trust the issuer to hold>",
                    "currency": "<the currency the issuer will hold>",
                    "issuer": "<the issuer's Stellar address>"
You can find <SECRET> on your Stellar settings page; everything else will obviously depend on what you're trying to do.

WARNING: POSTing your secret to is potentially insecure; you would be better off signing requests locally; a blog post on this may be forthcoming.

You'll then need to POST this to the API:
curl -X POST -d'<JSON>'
There's a bug in Stellar that means that newlines and/or indentation cause problems, so you'll need to make the above JSON just a single line and slot it in to the above command line.

Once you run that, you're done!


  1. Hi Daniel, I have a question for you: at the same time you trusted Coinex to hold up $20 NZD, did you somehow sent Coinex those $20 NZD to be holded? How?

    1. Hi Guille,

      Thanks for reading my blog post!

      An important concept in the Stellar world is that there isn't a single instance of each currency on the network. You can only ever acquire a currency that is issued by a particular gateway (e.g. "NZD issued by Coinex", "USD issued by Odd_Bloke", "GBP issued by Guille"). Crucially, several gateways can issue the same currency (e.g. the network could have both "NZD issued by Coinex" _and_ "NZD issued by Odd_Bloke").

      Another important concept is that you can't implicitly trust gateways. If I were to issue "USD issued by Odd_Bloke", it is _assumed_ that I have some actual matching dollars, so that someone who wants to cash out their "USD issued by Odd_Bloke" to real USD can do so. However, there's no guarantee that this is the case. People have to trust that I will actually cough up the cash.

      When I ran the code in this blog post, I was saying "I trust Coinex to pay out 20 NZD". This means that the Stellar network will allow people to transfer me "NZD issued by Coinex", up to 20NZD.

      Another way of thinking about currency on the Stellar network is as an IOU. So 20 "NZD issued by Coinex" is actually "Coinex owe you 20 NZD".

      Hope this helps,


  2. I got you know. You JUST trusted NZD for $20. Thanks for taking the time on writting the clarification. — Guille