Setting up federated addresses with Stellar

Fun fact: the username you sign up with on Stellar’s hosted web client is actually a federated address rather than a username. That is, the username gdb is actually short for If you control a domain, you can set up federated addresses for your domain.

We’ve now set up federated addresses on You can now use your client to make a payment to

 Setting up federation

You can set up federation for your domain too — it’s pretty easy (though per the below, the protocol may end up being changed). I’ll walk you through how a client or browser resolves


First, the client finds Stripe’s stellar.txt file by requesting the following URLs until one works:

We’ve set up our stellar.txt on, which is served as follows:

$ curl -i
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *


Note that the response sets an Access-Control-Allow-Origin: * header, so that the user’s browser can actually read the response.

 Federation server

Next, the client makes a request to the federation server with query string destination=gdb& (I think the duplicated gdb parameter is an artifact that will be end up being removed). We respond with a federation record:

$ curl -i ''
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *

  "federation_json": {
    "type": "federation_record",
    "destination": "gdb",
    "domain": "",
    "destination_address": "gpFfX9931eSbjUhtu3ujb6Tu7Z48u53uiL"

At this point, the client knows which address resolves to.


You can find the code for a sample federation server on Github. (If you write one in another language, you should add it to that repository!)

Note that the protocol is not fully stable yet. The current implementation is forked from Ripple’s, and it’s likely that the Stellar devs will want to give it a once-over, based on lessons learned, before fully baking it in.

It would be awesome to see someone create a hosted federation service. Users would set up to point to the service, provide the service with the corresponding SSL cert, and then configure their user accounts through a webface. I don’t think it’d be all that hard to build, and it could be a viable business on its own.


Now read this

#define CTO OpenAI

It’s been two years since I wrote #define CTO, in which I documented my quest for a role where I could have scalable impact by writing code. I’ve finally found that role, though not by seeking it — instead, I sought out a problem more... Continue →