How to Host Your Counterparty Images and Json Files on GitHub

With the advent of easyasset.art and ardrive, what would the appeal of storing your Counterparty token data on GitHub be? First, both of the above solutions rely on the Arweave network and the chain’s native token — AR. When easyasset’s wallet runs out of AR tokens, the site goes down meaning no one can use it until someone volunteers to send additional AR tokens to the wallet listed on the page. If you would like to donate, simpleswap.io is my go-to for obtaining AR. You can swap almost any coin on any chain for it.

Second, each require you to do an on-chain Bitcoin transaction every time you want or need to update your token’s description. By pointing your Counterparty Token’s description to a json file stored on GitHub, there is no fee or on-chain transaction necessary to make changes to the description!

There is one very large caveat to this method though. It only works with Counterparty tokens that ARE NOT part of a collection.

The reason for this is that once your token is accepted into an official collection (Dank Rares, Wojaks, Fake Rares, Etc.) your token description gets written into that collection’s json file and is considered “locked in.” Not to say it is impossible to have the description of an official project token changed, but it is not easy.

Now that we know the why, let’s look at the how.

GitHub Setup

If you don’t already have an account on GitHub, create one at https://github.com/signup.

Once you are setup and logged in, click on your account image at the top right of the screen and choose “your repositories”. Alternatively, you can type https://github.com/yourusername?tab=repositories into your browser.

Next, click “new” to create a new repository.

Repositories are simply folders that you use to keep yourself and your projects organized on the site.

Give your repository a name such as “jsons.” Enter a description if you wish and then click “Create repository.”

Repeat this process to create a second repository called “Images.”

With these two repositories created, you can now upload files into them. Go back to your repository page and click on the one titled “Images.”

Preparing the images for use in the json file

For each Counterparty token you need at least two images — a thumbnail and a main. You can include other images such as high resolution versions, still images from a gif or video file, text files, etc. But to keep it simple, we will only be using two in this tutorial.

The thumbnail image must be 48x48 pixels and a .png file. The main image can be whatever you want it to be (.jpg, .png, .gif, .mp4, etc.).

Once you have your two images ready for upload, click on the grey “+” symbol and choose “Upload files.” After they have uploaded, click the green “Commit changes” button.

Now you need to find what is called the raw link to each image. There may be an easier way to do this, but this is how I accomplish it.

Go to your images repository and click on an image file.

Clicking on the thumbnail image takes me to https://github.com/subterranean1/images/blob/main/PEPESHOOD%20thumb.png

This link will not work in your Counterparty json. Instead, right-click on the image and choose “open image in a new tab”.

Upon clicking on the tab, I get https://raw.githubusercontent.com/subterranean1/images/refs/heads/main/PEPESHOOD%20thumb.png. I have found that this link works with or without “refs/heads” so you could shorten the link to https://raw.githubusercontent.com/subterranean1/images/main/PEPESHOOD%20thumb.png if you wanted to.

Copy this link and paste it into an open document or notepad file on your computer. Also, paste it into a third browser tab to make sure the link is working. If it is, the image will be on a black screen, not in the GitHub frame.

Repeat the above process for your main image.

Constructing you json file

With your two image links copied, you are now ready to construct your json file. The format is:

Obviously you will replace all the data with your own token data. You can copy mine for editing here.

This is the bare minimum that you want to include with your token — the token name, token creator, images, and creator’s twitter account. There are many other items which can be included in your json. Some good examples can be found here.

Save your json file on your computer with the token name followed by .json. For example mine is PEPESHOOD.json.

Note — if using a text editor like Windows Notepad — you must change the “save as file type” from the default “Text Documents (*.txt)” to “All files”. Otherwise your file will be named PEPESHOOD.json.txt (even if it is not displayed that way in the Explorer). To ensure you have named it correctly, you would choose view/show/file name extensions if using a Windows machine.

Uploading the json file to GitHub

Go back to your repositories tab and click on the jsons repository.

Click on the grey Add file button and choose “upload files”

Navigate to the file on your computer and click it. Once it is uploaded, click the green “commit changes” button.

Now we need to find the raw link to the json file. This is what we will be putting in the description field in freewallet.

Click on your json file in your github repository

Click the grey “raw” button and the json file will be opened up in a new browser tab.

Copy this link and save it for later use

Changing the description in Freewallet

Now we need to point the token to this json file. This is done by updating the description in freewallet.

Type the token name into the search field. In this case, PEPESHOOD.

Right click on the name and choose “Change PEPESHOOD description”

Paste in your raw link that you copied from github earlier.

Important note about fees

It is imperative that you increase the fee from the recommended by to an amount 3 to 4 times as large as what is displayed. the reason for this is because descriptions contain a large amount of data which causes the transaction to be broken up into multiple sends. This makes the effective fee rate drop. This can also happen when your wallet has lots of unspent transactions (UTXO’s). In a high-fee environment this may cause your transaction to get “stuck” in the mempool for a long time.

Click the green “change description” button after increasing the fee.

Click “Yes” to proceed.

Click “View Transaction” to track the progress of the transaction.

Copy the Transaction Hash

I pasted the Transaction Hash into mempool.space which showed what I was describing above. If I had left the transaction fee at the amount recommended in Freewallet, my Effective fee rate would have been approximately 1 sat/vB and it may have never confirmed. Even with my increased fee (7.14 sat/vB) my effective rate dropped to 3.66 sat/vB which was just enough to allow the transaction to clear the mempool in 2 blocks (approximately 20 minutes).

Once the transaction has cleared, you can inspect the token on a Counterparty block explorer such as tokenscan.io (formerly known as xchain.io).

You can see that the description has been successfully been changed to my json file being stored on GitHub. So I must be done right? Oh no!!! I used the wrong image. There was supposed to be a Pepe Flyer V2 shoe in the bottom left corner of the card. Here is where the benefit of all of this work comes in. I don’t have to go through another description change, increased transaction fee, and confirmation time. I can simply update the json file on GitHub and the token will be updated automagicly.

This is done by returning to your json file on GitHub and clicking the pencil icon. Once you have made the correction, a green “Commit changes” button will appear. Click that to save the file.

After changing the image link in the GitHub-hosted json file and returning to tokenscan, the correct image is now displayed (without a Bitcoin transaction).

That was a long-winded tutorial which may or may not be needed by anyone but I’m glad I went through the process while writing this article to see it work in real time. And remember — this method only works with Counterparty tokens that ARE NOT part of a collection.