Publish an App to the 21 Marketplace

Posted by John Granata, Michael Goldstein

Publish an App to the 21 Marketplace

Update: Upgrading to the new 21mkt network? Please see the upgrade instructions.


In this tutorial we'll show you how to publish your bitcoin-payable web app to the 21 Marketplace. After reading, you should be able to list your app on the 21 Marketplace for others to find and purchase. The steps we will cover are:

  1. Download the basic app manifest template
  2. Fill in the template with information about your app
  3. Publish your app to the 21 Marketplace

Let's get started!

Step 1: Download the app manifest template

We will assume that you've already set up a project folder to house your bitcoin-payable web service. The structure of that project folder may look something like this so far:

└── static

where is your server code powered by the 21 Bitcoin library, and is an optional script provided to help users sequence interactions with your API. Now we need to create an app manifest. The manifest file is a specification for your bitcoin app that provides information used for indexing and providing potential customers with usage details.

The manifest is a YAML file that extends a Swagger REST API definition. The full Swagger specification is available here.

Download the basic manifest template:

curl -L >> manifest.yaml

This template can be edited manually in a text editor, or you can can open the template in the online swagger editor by clicking here, selecting File > Import URL... and pasting in the link to the template above. You can then copy the file to another device (if necessary) using the scp utility available on Linux and Mac.

You can also download the bitroute sample app here.

git clone
cd bitroute

Step 2: Fill in the template with information about your app

The blank app manifest template should look like this:

  - http
basePath: /

Fill in each field with your app-specific information. Below is a simple example that shows how to populate the manifest with the necessary information for publishing:

  title: 'Bitroute'
  description: 'Run a traceroute on demand for bitcoin.'
  x-21-quick-buy: '21 buy ""'
  x-21-category: utilities
  x-21-app-image: ""
    min: 3000
    max: 3000
    name: 21
host: [fcce:a977:eef4:2ea3:fd86:0000:0000:0001]:6003
  - http
basePath: /

Below is a brief description of the fields in the manifest specification:

Field Description
title The title of your app, which must be less than 30 characters.
description Short (less than 50 character) description of your app.
x-21-quick-buy A quick usage example that a user can copy and paste into the command line to make a simple purchase. This is displayed in the app preview when a listing is selected in the Marketplace.
x-21-category The category for your app. Choose (1) from: blockchain, entertainment, social, iot, utilities, or markets.
x-21-app-image The image displayed next to your app listing. Upload your image here and paste the generated URL in this field.
x-21-total-price List the minimum and maximum price for endpoints in your app. If there is a single endpoint with only one price, make the minimum and maximum equal.
name The author name to display with the published listing.
email The email associated with the published listing.
host The host from which the app is being served. This can be a domain name or IP:PORT. This can be a domain name or IP:PORT. For IPv6 addresses, the address must be placed in brackets (for example, [::1]) and you may use either a full address (with 32 digits and 7 colons) or an address condensed according to the IPv6 formatting rules). If you're using the 21mkt ZeroTier network, you can find your IPv6 address by running 21 market status
schemes The URI scheme for accessing your web service.
basePath The root path that is prepended to all other paths. For example, if the basePath is specified as /api, then a path designated as /test in the manifest will render as /api/test in your app description. Ensure there is no trailing / in the basePath field.

For additional information on writing an app manifest, read the 21 App Manifest Walkthrough tutorial.

Step 3: Publish your app to the 21 Marketplace

Start your app. Open a new terminal. If you have a 21 Bitcoin Computer, SSH into it. Now that your app is documented and running, publish your app to the 21 Marketplace from the command line with:

21 publish submit <PATH_TO_MANIFEST>

For example,

21 publish submit ~/myapp/manifest.yaml

That's it! Check your inbox for error notifications in case your app was not accepted by the marketplace by running 21 inbox at the command line. Go view your app here. Congratulations, you just published your first bitcoin-payable app to the 21 Marketplace!

If you encountered an error, run the 21 publish list command shown below to see whether your app was published. If it was, you may need to remove it from the Marketplace by running the 21 publish remove command described below and then re-publish it with the 21 publish submit command described above.

You can list your published apps from the command line with:

21 publish list

You will see an app ID listed next to each app you've published to the marketplace. You can unpublish your app at any time with:

21 publish remove <APP_ID>

If you change your manifest.yaml file, you must re-publish it for the Marketplace to recognize any changes by re-running by 21 publish <path_to_your_manifest_file>. As long as your host IP address remains constant, any changes will be reflected in the same app listing.

If you change IP addresses or domains, you need to run 21 publish remove to remove your app from the Marketplace and then re-add the app by running 21 publish submit. You will see duplicate apps, only one of which is valid, if you do not remove the original app before re-publishing.

Debugging an error

If you received a notification that your bitcoin app did not publish to the 21 Marketplace successfully, please check to make sure your manifest meets the requirements outlined in this document. Make sure you've stayed under the 2MB file size limit for your manifest, and that your spec doesn't violate any of the constraints, including character limits, number of keywords, category, etc.. Bitcoin apps will be removed from the index if any of the fields are abused.

Upgrade Tutorial

This section will explain how to upgrade existing Marketplace apps on the 21market network to be compatible with the new 21mkt network. If your server has its own public IP or DNS, it does not need to be updated.

  1. Leaving the old 21market network will occur automatically when running any 21 command.
  2. Join the new ZeroTier network by running 21 market join.
  3. Update your server code to listen for IPv6 requests:
    • If running a Flask server, change””, port=XXXX) to”::”, port=XXXX) in your main method.
    • If running a Django server, change the runserver command from python3 runserver to python3 runserver [::]:XXXX.
  4. Remove the /manifest endpoint from your server code. The 21 Marketplace crawler will no longer hit this endpoint; any changes you want to make to the manifest must be explicitly updated by re-publishing your app.
  5. Re-publish your app by running 21 publish submit <path_to_your_manifest_file> --parameters 'host="AUTO" port="XXXX"'. (The 'host=AUTO' flag enables auto-detection of your host on ZeroTier.)

If you are running a server via 21 sell, run 21 sell and follow the instructions to update these apps.

For more information about app manifests, click here.