Adding Trustlines to the Keybase Wallet

Trustline is an anti-spam protection, the user needs to trust the issuer of an asset to be able to receive that asset.

Adding Trustlines to the Keybase Wallet

Enabling the Keybase wallet to hold assets in addition to Stellar Lumen.

This tutorial shows, in simple steps, how to add a trustline to the Keybase wallet using the tools provided by the Stellar website.

Why add trustlines to the Keybase wallet?

The wallet built into the Keybase app holds Stellar Lumens (XLM). To hold other assets in the wallet, it is necessary to add a trustline for that asset. Other assets may include other crypto currencies, such as Ethereum (ETC) and Bitcoin (BTC). Also included in other assets can be fiat currencies such as EUR and USD, using asset tokens.

The Stellar Consensus Protocol allows tokens for any asset which can be bought, sold, and owned. Something as global as gold and silver, or something as local as BerkShares. Once a trustline is established for them, the tokens representing that asset can be held in your Keybase wallet.

The built-in system and its limitations

The wallet in the Keybase app has the ability to add trustlines to the account built in. Unfortunately, for an emerging, or unknown asset, adding a trustline is not always possible using that option. The main Stellar website has a tool to accomplish this, as long as someone has issued a token on the Stellar Consensus Protocol to represent that asset.

Security Warning

Using the tools on the Stellar website requires you to enter your Keybase wallet’s secret key. With the Keybase wallet, or any other wallet, you are the bank. All the crypto value of your wallet is locked behind the secret keys of that wallet. Protect that secret key like you would the keys to a vault.

There are some simple things you can do to help keep your secret key secret in this process.

What we will be doing

In this tutorial we will be adding the asset STELLARTALK


Any asset or token listed with Stellar can be added using this method, including ones which can be added using the built in controls of the Keybase wallet.

How to add a trustline

You will need to have both your web browser, and your Keybase app open. It is easier to do this using the desktop version of the app. It is possible to use the mobile version of the app as well, just not as easy to manage the multiple windows needed.

Build the transaction to add a trustline

Connect to the Stellar public network in Transaction Builder

Stellar provides a set of pages, called the “Laboratory” for dealing with the network without an additional program. There are two networks, testing and public. The testing network allows developers to try different things without creating real transactions on the ledger. The public network is the “real” network, were everything goes into the ledger, and becomes a part of the record. The Transaction Builder is the tool where we need to begin.

Open the browser in a private window and go to the address

Check that your browser indicates that it is a secure site, usually a lock icon in the address bar.

address bar showing the HTTPS lock icon
Look for the lock icon, often green, in the address bar.

If not STOP! Find out why your connection is not secure and try again.

Do not continue without a secure, HTTPS, session!

Check the top right corner of the web page to be sure you are not on the test network.

Showing a connection to the test network
A connection to the test network

If you are, then click on the “Public” button to switch to the live system.

showing a connection to the public network
A connection to the public network

Click the link to the “Transaction Builder”

Image of the Transaction Builder link
Click the link to Transaction Builder

Next we have to gather the information about the transaction we want to build and enter it into the form provided.

Image of the Transaction Builder page
The empty Transaction Builder form

Enter your Stellar Address

Adding a trustline to your wallet has to be connected to your Stellar address. That address has to be entered into the form. These steps will accomplish this.

Switch to the Keybase app and open your wallet.

Image of the main wallet screen in the Keybase app
The Keybase wallet

Next to the name of your account is a gear icon. gear icon for access to settings

Click that to open the setting for the wallet, which includes the public and secret keys for your account.

Image of the settings screen in the Keybase app wallet
The Keybase wallet settings

Click on the clipboard icon  next to the box with your Stellar Address. This will automatically copy your Stellar address to the clipboard.

Return to the Transaction Builder in your browser.

the source account field
Click in the “Source Account” field
the source account field with data
Paste the just copied address here

Generate a sequence number

Every transaction on the Stellar network must have a sequence number. The sequence number is associated with the account, and should always be 1 greater than the current number. Knowing what that number is, when many things can affect it, is impractical for most people. The Transaction Builder can look up the current sequence number and automatically fill in the new value for you.

Image of the button to generate a new sequence number
Click the “Fetch next sequence number …” button
Results from a sequence number fetch
Sample of results from a sequence number fetch

Enter the information about the trustline to create

Find the “Operation Type” field, and click on the “Select operation type” dropdown.

The Operation Type field
Click on “Select operation type” dropdown

select “Change Trust” from the dropdown. Do not get this confused with the “Allow Trust” which is a different thing.

Operation type list dropdown
Choose “Change Trust”

New fields are added to the Transaction Builder form based on the operation type selected. The Change Trust operation requires information about the asset to be trusted. Asset names can be long, or short, with the long version having a limit of 12 characters and the short version having a limit of 4 characters.

Buttons for name size limits
Name length limits

The asset selected for this tutorial, STELLARTALK, obviously will not fit in a 4 character field, so we need to select the “Alphanumeric 12” button.

The Alphanumeric 12 button
Click on the “Alphanumeric 12” button

Now there are two new boxes for the information about the asset to trust.

The asset data fields
The asset data fields

In the Asset Code text box, enter the code for the asset, STELLARTALK for this tutorial.

The asset code
Enter the Asset Code

In the Issuer Account ID text box, enter the account number for the asset, GD6NJNNQ75TB4B5UM3PGRUMSM2JCMYPQTDDHGIJVLEZEHNOM5GVZX5VD for this tutorial.

The asset Issuer Account ID
Enter the asset Issuer Account ID

The Asset information should now look like this.

The asset data complete
The complete data for the asset fields

The other two fields, Trust Limit and Source Account, remain blank.

Set the time bounds

The transaction we are building can be set to happen at a specific time, and can be set to expire at a later time. The later upper bound is not when an offer, or some other transaction is cancelled, it is when this operation is no longer valid. If, for some reason, there is enough network traffic that this transaction is not executed within the upper limit set, it will simply not be executed and never be added to the ledger.

The Time Bounds fields
The Time Bounds fields

When adding a trustline, this may not be so important, but for other operation types it could be significant. As a standard habit to develop, we can set an upper time bound now anyway. It has even been made real simple, by adding a button to set the time to 5 minutes from now. Even though this is a tutorial, and could be slow to work through, it should be done in 5 minutes or less, so click the handy button to “Set to 5 minutes from now.”

The Time Bounds 5 minute button
Set time bounds to 5 minutes

Sign and submit the transaction

At this point the transaction has been successfully created.

The success message
The created Transaction Envelope

The Transaction builder says that the transaction still needs to be signed before it can become part of the ledger.

Load the Transaction Signer page

After building a transaction, the next step is to sign the transaction. There is even a handy button to take us to the Transaction Signer page. Click the button “Sign in Transaction Signer” and the next web page is ready to use.

The link to the Transaction Signer
Click the “Sign in Transaction Signer” button

Sign with your Keybase Wallet Secret Key

Go back to the Keybase app, which should still be on the wallet settings. Keybase gives you an additional reminder about the importance of your secret key.

Image of the warning from the Keybase app wallet
Don’t ignore this warning

Click on the clipboard icon next to the hidden text of the secret key. This copies the secret key to the clipboard, without revealing it on the screen.

Copy the secret key
Copy the secret key to the clipboard

Return to the Trasaction Signer page in your browser. Double check, one more time, that it is a secure connection. This is the last chance to protect your secret key.

address bar showing the HTTPS lock icon
Look for the lock icon, often green, in the address bar.

Paste your secret key into the Add Signer box. You only need to do it once.

Add Signer text bot
Paste the secret key from Keybase.

Each entry in the text box opens another text box to add another signer. The second box is for those who have set up their account to require more than one signer to allow operations to be done.

Submit the transaction to the ledger

The transaction is now signed, and ready for the next step.

Signed transaction
Transaction signed and ready to submit.

Now click the Submit to Post Transaction endpoint button.

Post transaction submit button
Click the “Submit to Post Transaction endpoint” button

The last chance for backing out is now. Click the Submit button and the transaction will be submitted to the ledger.


submit to ledger button
Click the “Submit” button to sent the Transaction to the ledger

Each trustline added to the account requires a 0.5 XLM reserve. If your account does not have that much extra available, the transaction will be denied.

submit to ledger failed
Transaction failed for lack of needed reserve

If the account does have the needed reserve, then the success message will be your reward.

submit to ledger succeeded
Transaction succeeded and is the ledger

Verify new trustline

Return to the Keybase wallet settings and click on the Manage trustlines button near the bottom.

Manage trustlines button
Manage trustlines button

If all has been done correctly, you will have STELLARTALK in your list of trustlines.

New trustline added
STELLARTALK in the list of trustlines

Now your Keybase wallet can hold STELLARTALK tokens, and you can send, receive, buy, sell, and trade them as easily as you can Stellar Lumen.

The same process can be used to add any asset tokens available on the Stellar network, as long as you know their Asset Code, and the Issuer Account ID.

[1]: The HTTPS protocol encrypts all the data you send to the server. Anyone evesdropping on your network will not be able to see the secret key you send to the website.

[2]: The data, including your secret key, is entered into fields of a form. Most browsers will store form data to make it faster to fill in the same form when you return to that site. That form data will include your wallet’s secret key, which you don’t want stored anywhere but the Keybase wallet itself. Using private mode, if the browser is compliant, prevents the storing of any information from the session, including form data, and cookies. You will still have access to data previously saved from a regular (non-private) session, such as login information if needed.

[3]: Using the app’s ability to place the secret key directly into the clipboard prevents errors in typing it and prevents a key logger from seeing it when you type it. It will not be shown on the Keybase app. It will, however, be visible on the Transaction Signer page.

Eager to stay in the loop?

Subscribe to the BizzNerd newsletter! and join our team on Keybase.  We are giving all new members 1.5 XLM as a welcome gift.

If you want to find out more info about Keybase app read “Keybase App Tutorial“.

Show More
Back to top button