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:
- Download the basic app manifest template
- Fill in the template with information about your app
- 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:
. ├── index.py └── static └── client.py
index.py is your server code powered by the 21 Bitcoin
client.py 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.
Download the basic manifest template:
curl http://bit.ly/1TRCjra -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
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
You can also download the
bitroute sample app here.
git clone https://github.com/21dotco/bitroute.git cd bitroute
Step 2: Fill in the template with information about your app
The blank app manifest template should look like this:
info: title: description: x-21-quick-buy: x-21-category: x-21-app-image: x-21-total-price: min: max: contact: name: email: host: schemes: - 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:
info: title: 'Bitroute' description: 'Run a traceroute on demand for bitcoin.' x-21-quick-buy: '21 buy "https://mkt.21.co/test_user/traceroute/traceroute21?uri=21.co"' x-21-category: utilities x-21-app-image: "https://cdn.filepicker.io/api/file/gOiZB2CjT1W82di7IQ9m" x-21-total-price: min: 3000 max: 3000 contact: name: 21 email: firstname.lastname@example.org host: [fcce:a977:eef4:2ea3:fd86:0000:0000:0001]:6003 schemes: - http basePath: /
Below is a brief description of the fields in the manifest specification:
||The title of your app, which must be less than 30 characters.|
||Short (less than 50 character) description of your app.|
||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.|
||The category for your app. Choose (1) from: blockchain, entertainment, social, iot, utilities, or markets.|
||The image displayed next to your app listing. Upload your image here and paste the generated URL in this field.|
||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.|
||The author name to display with the published listing.|
|The email associated with the published listing.|
||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,
||The URI scheme for accessing your web service.|
||The root path that is prepended to all other paths. For example, if the
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>
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
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
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.
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.
- Leaving the old
21marketnetwork will occur automatically when running any
- Join the new ZeroTier network by running
21 market join.
- Update your server code to listen for IPv6 requests:
- If running a Flask server, change
app.run(host=”::”, port=XXXX)in your main method.
- If running a Django server, change the
python3 manage.py runserver 0.0.0.0:XXXXto
python3 manage.py runserver [::]:XXXX.
- If running a Flask server, change
- Remove the
/manifestendpoint 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.
- 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.