OpenBazaar has two distinct components: a server and a client.
The ‘server’ is the network daemon that connects with the OpenBazaar P2P network and contains the node’s database. It is the ‘business end’ of the OpenBazaar application, as it connects directly with other nodes on the network, caches data, digital signs contracts, and holds private keys etc. The server can either run locally (i.e. on your computer) or remotely on a virtual private server (e.g. Digital Ocean, Docker, Heroku).
The ‘client’ is what the user interacts with operate the functions of the server. The client uses a combination of REST and Websocket (WS) APIs to control the network and market function of the server. This enables developers to create alternative or feature-specific clients for OpenBazaar.
If the OpenBazaar server is running locally, the base URL will be:
http://localhost:18469/api/v1/
If the server is hosted remotely, ‘localhost’ is replaced by the IP address of the remote server. For example:
http://128.199.118.253:18469/api/v1/
For remote access, the server must be run with the necessary arguments to support remote network access. We will link to documentation explaining how to do this soon.
The response format is JSON, with exception to image API calls.
Returns the profile data of the user’s node, or that of a target node.
http://localhost:18469/api/v1/profile
- guid=[guid of the target node]
- optional
- The global unique identifier (guid; 40 character hex string) of the node to get the profile data from
- If the guid is omitted, your own node’s profile will be returned
Example:
{
"profile": {
"website": "",
"about": "drwasho's store",
"guid": "375ead0967e63b6cec49f28d3be8731b20f081db",
"vendor": true,
"name": "drwasho",
"text_color": 16777215,
"social_accounts": {},
"header_hash": "7de0c4aab5929ad7c413175ec9dd2ae1476e19b9",
"encryption_key": "0374e542b2faa53d40b43f36c722d9f40cbf40dd11da3afb6508010a8b228126",
"secondary_color": 3243448,
"moderator": true,
"moderator_list": [
""
],
"pgp_key": "",
"nsfw": false,
"location": "UNITED_STATES",
"avatar_hash": "",
"handle": "",
"primary_color": 551582,
"background_color": 407379,
"email": ""
}
}
JSON is returned with the following objects:
- Website
- Website of the user, if any
- About
- About description
- GUID
- Global unique identifier of the node
- 40 character hex string
- Vendor
- Is the node a Vendor (i.e. do they sell stuff)?
- Boolean
- Name
- Name of the user
- Text Color
- Custom theme text color of the node
- Social Accounts
- Profile name of Facebook, Snapchat, Instagram, & Twitter accounts
- Header Hash
- Hash of the header image for the node’s page
- Encryption Key
- Public key of the node
- Secondary Color
- Custom theme secondary color of the node
- Moderator
- Is the node a Moderator?
- Boolean
- Moderator List
- Array of Moderators that the node has subscribed to
- PGP Key
- PGP public key of the user
- NSFW
- Not suitable for work (i.e. is the contents of the page/store not suitable for work) [Boolean]
- Location
- Country location of the node (helps determine whether items can be delivered to your location)
- Avatar Hash
- Hash of the avatar image\
- Handle
- Blockchain ID handle of the node, if any
- Primary Color
- Custom theme primary color of the node
- Background Color
- Custom theme background color of the node
- Email
- Email of the node, if any
View your node’s profile data
<html>
<body>
<form action="http://localhost:18469/api/v1/profile" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="My Profile">
</form>
</body>
</html>
View another node’s profile:
<html>
<body>
<form action="http://localhost:18469/api/v1/profile" method="get" enctype="multipart/form-data" target="_blank">
<input type="text" name="guid" placeholder="Enter GUID here" required/>
<input type="submit" value="View Profile" />
</form>
</body>
</html>
Returns the profile data of the user’s node, or that of a target node.
http://localhost:18469/api/v1/get_image
- guid=[guid of the target node]
- optional
- image=[hash]
- required
If the guid is omitted, the server will look for the image hash in your own node’s database.
The image will be returned in .jpg format.
View an image on your own node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_image" method="get" enctype="multipart/form-data" target="_blank">
`<input type="text" name="hash" placeholder="Image hash" required />
<input type="submit" value="View Image" />`
</form>
</body>
</html>
View an image on another node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_image" method="get" enctype="multipart/form-data" target="_blank">
Target Node GUID<br>
<input type="text" name="guid" placeholder="Target node GUID" /><br><br>
Image Hash<br>
<input type="text" name="hash" placeholder="Image hash" />
<input type="submit" value="View Image" />
</form>
</body>
</html>
Returns the listings of the user’s node, or that of a target node.
http://localhost:18469/api/v1/get_listings
- guid=[guid of the target node]
- optional
If the guid is omitted, the server will look for listings in your own node’s database.
Example:
{
"listings": [
{
"contract_hash": "042fe5466b814394ea27532a7436e596414e93a3",
"category": "Figurine",
"nsfw": false,
"title": "Yoda Figurine",
"thumbnail_hash": "f1d0a23bd9417024118906ca6b6432abee51f5f5",
"price": 0.0010000000474974513,
"origin": "UNITED_STATES",
"currency_code": "BTC",
"ships_to": [
"UNITED_STATES"
]
}
]
}
JSON is returned with the following objects:
- Contrach Hash
- SHA256 hash of the contract
- Serves as the unique identifier for the contract
- Contract is tamper-proof
- Category
- User-generated category
- Doesn't conform to a standardised category
- NSFW
- Boolean value
- Not suitable for work
- Title
- Title of the listing
- Thumbnail_hash
- SHA256 hash of the image displayed in the listing's thumbnail (on the discover page of the reference client)
- Price
- Price of the item
- Origin
- Where will this item be shipped from?
- This location is determined according to the Vendor's settings
- Currency Code
- What currency is the listing priced in?
- Ship To
- What countries/regions will the item be shipped to?
View listings on your own node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_listings" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Listings" />`
</form>
</body>
</html>
View listings on another node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_listings" method="get" enctype="multipart/form-data" target="_blank">
Target Node GUID<br>
<input type="text" name="guid" placeholder="Target node GUID" /><br><br>
<input type="submit" value="Get Listings from Node" />
</form>
</body>
</html>
Returns the nodes following your node or a target's node.
http://localhost:18469/api/v1/get_followers
- guid=[guid of the target node]
- optional
If the guid is omitted, the server will look for followers in your own node’s database.
Example:
{
"followers": [
{
"avatar_hash": "43e0b057e37f34fdc6f8f421af0875c63a20e321",
"guid": "53328edb89afa8a653b4fa062f0cb255aa4a1e50",
"handle": "@chrispacia",
"name": "Chris Pacia",
"nsfw": false
},
{
"avatar_hash": "27c221cd1b99a0feed173dc52ae9239e175176e3",
"guid": "2a7a579ca9a43a1b3d8338546c95196c5ef46170",
"handle": "@drwasho",
"name": "drwasho",
"nsfw": false
}
]
}
JSON is returned with the following objects:
- Avatar Hash
- SHA256 hash of the avatar image of the node
- GUID
- Handle
- Name
- NSFW
View listings on your own node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_followers" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Followers" />`
</form>
</body>
</html>
View an image on another node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_followers" method="get" enctype="multipart/form-data" target="_blank">
Target Node GUID<br>
<input type="text" name="guid" placeholder="Get Followers" /><br><br>
<input type="submit" value="Get Followers from Node" />
</form>
</body>
</html>
Returns the nodes being followed by your node or a target's node.
http://localhost:18469/api/v1/get_following
- guid=[guid of the target node]
- optional
If the guid is omitted, the server will look for nodes being followed in your own database.
Example:
{
"following": [
{
"avatar_hash": "0ad0516a91bbd9147e1f23ccb5f3310181d924ed",
"guid": "f9ea0b394c58e14c75e8a754ae721ad8bb0cf850",
"handle": "",
"name": "SamTest",
"nsfw": false
},
{
"avatar_hash": "23aeab637fc55e8b9d73dfba28ab111a53261f46",
"guid": "b1a4a8b4b7e934c7f8b119a671044c90a7513968",
"handle": "@seed1",
"name": "OpenBazaar Seed Server",
"nsfw": false
}
]
}
JSON is returned with the following objects:
- Avatar Hash
- GUID
- Handle
- Name
- NSFW
View nodes you are following:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_following" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Following" />`
</form>
</body>
</html>
View an image on another node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_following" method="get" enctype="multipart/form-data" target="_blank">
Target Node GUID<br>
<input type="text" name="guid" placeholder="Target Node" /><br><br>
<input type="submit" value="Get Following from Node" />
</form>
</body>
</html>
Returns the settings of your node
http://localhost:18469/api/v1/settings
None.
Example:
{
"blocked_guids": [""],
"refund_address": "n2eMqTT929pb1RDNuqEnxdaLau1rxy3efi",
"refund_policy": "No refund policy",
"notifications": true,
"seed": "e4ed7abcd397c3adf9f13a8dd31db6c99dbf48315e1c6d75196318c0bb7bfedd",
"shipping_addresses": ["[{\"name\":\"Washington Sanchez\",\"street\":\"1060 W Addison\",\"city\":\"Chicago\",\"state\":\"Illinois\",\"postal_code\":\"60613\",\"country\":\"UNITED_STATES\",\"displayCountry\":\"United States of America (The)\"}]"],
"terms_conditions": "No terms or conditions",
"language": "en",
"ssl": true,
"country": "UNITED_STATES",
"time_zone": "10",
"libbitcoin_server": "",
"currency_code": "BTC"
}
JSON is returned with the following objects:
- Blocked GUIDs
- Nodes that you have blocked
- Refund address
- The destination address of any refunds you may received
- Refund policy
- Refund policy for goods and services you sell as a Vendor
- Will be added to every listing
- Notifications
- Boolean
- Will determine whether you see notifications within the client
- Seed
find out exactly what this is
- Shipping addresses
- Addresses that items can be sent to
- Supports multiple addresses
- Terms and conditions
- Terms and conditions for goods and services you sell as a Vendor
- Language
- Language code
- SSL
- Boolean
- Determines whether SSL connections are enabled
- Country
- Country code
- The country set in this field helps the client determine whether a good or service is accessible to you when browsing listings
- Time zone
- UTC
- Libbitcoin server
- IP address of a federated libbitcoin server
- Default libbitcoin servers will be used if left empty
- Currency code
- Determines what currency prices are calculated in from Bitcoin or visa versa
View your node's settings:
<html>
<body>
<form action="http://localhost:18469/api/v1/settings" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="View Settings" />`
</form>
</body>
</html>
Retreive a history of all notifications your node has received. Notifications can be sent due to:
- A node following you
- Events related to a purchase or sale
http://localhost:18469/api/v1/get_notifications
- limit-[number of most recent notifications]
- Default is unlimited
- Counts from most recent
{
"read": true,
"handle": "@bdunbar",
"title": "",
"order_id": "",
"timestamp": 1449103787,
"image_hash": "38f4cae21cef9805e085fb6d21b8108030b4f612",
"guid": "fa5025f8ac9fcba532cff9608d1c080a84e2f7a1",
"type": "follow",
"id": "a84a2d6b67b237e0808c711077b60c069f713213"
}
JSON is returned with the following objects:
- Read
- Boolean
- Has this notification been read or not
- Handle
- Handle of the node responsible for the notification
- Title
- Title of the listing, if the notification refers to a contract
- Order ID
- Order ID of the listing, if the notification refers to a contract
- Timestamp
- When the notification arrived
- Unix time
- Image hash
- SHA256 hash of the avatar image of the node responsible for the notification
- GUID
- GUID of the node responsible for the notification
- Type
- Type of notification
- ID
- Unique identifier of the notification
View nodes all of your notifications:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_notifications" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Notifications" />`
</form>
</body>
</html>
View 5 of the most recent notifications:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_notifications" method="get" enctype="multipart/form-data" target="_blank">
Target Node GUID<br>
<input type="number" name="limit" min="1" required/><br><br>
<input type="submit" value="Get Notifications" />
</form>
</body>
</html>
Retrieves all chat message received from other nodes.
http://localhost:18469/api/v1/get_chat_messages
- guid=[target node]
- required
- limit=[max number of chat messages to return]
- start=[the starting point in the message list]
{
"outgoing": true,
"handle": "",
"read": false,
"timestamp": 1449115105.901165,
"avatar_hash": "",
"message": "Testing 123\n",
"guid": "fa5025f8ac9fcba532cff9608d1c080a84e2f7a1"
}
JSON is returned with the following objects:
- Outgoing
- Boolean
- Indicates whether this message was sent or received
- Handle
- Handle of the node responsible for the message
- Read
- Boolean
- Timestamp
- In Unix time
- Avatar hash
- Message
- Message text
- GUID
View messages from a specific node:
<html>
<body>
<form action="http://localhost:18469/api/v1/get_chat_messages" method="get" enctype="multipart/form-data" target="_blank">
<input type="text" name="guid" required/><br><br>
<input type="number" name="start" min="1"/><br><br>
<input type="number" name="limit" min="5"/><br><br>
<input type="submit" value="Get Chat Messages" />`
</form>
</body>
</html>
Retreives a list of outstandng conversations.
http://localhost:18469/api/v1/get_chat_conversations
None.
{
"unread": 0,
"last_message": "Your store is awesome!\n",
"timestamp": 1449102448.72862,
"encryption_key": "66613133316636316462376131316232636631306332653763323364356162646665313365646339353564306538316536343534663736303763346566373139",
"avatar_hash": "",
"guid": "04b94de3d69aadbbcef31e6059fc5255655df45a"
}
Returns JSON with the following objects:
- Unread
- Number of chat messages unread
- Last message
- Last message text
- Time stamp
- Encryption key
- Public key of the target node
- Avatar hash
- GUID
<html>
<body>
<form action="http://localhost:18469/api/v1/get_chat_conversations" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Chat Conversations" />`
</form>
</body>
</html>
Retrieves the listings created by either your node or a target node.
http://localhost:18469/api/v1/contracts
- id
- Unique identifier of the contract
- SHA256 of the JSON formatted contract (40 character hex string)
- required
- guid
- GUID of the node if the call is made to a target node
- If omitted, the API will search for a contract ID created by your own node
{
"vendor_offer": {
"signature": "d6dc2a4b44b143971a328d5fc8509913fe2446f2a701257091c53449fa1a6f0f4e2f901c3e27b0d61aaaadd38d481aa39bb158313cbc15357ff4656d265cbb0e",
"listing": {
"item": {
"category": "star wars",
"description": "Squad goals",
"price_per_unit": {
"bitcoin": "0.001"
},
"title": "Jedi Squad",
"process_time": "3",
"image_hashes": [
"a26e08897885013fd930ade07772225fd98a267e"
],
"nsfw": false,
"keywords": [
"star wars",
"jedi"
]
},
"moderators": [
{
"fee": "10.0%",
"name": "BDunbar",
"blockchain_id": "@bdunbar",
"avatar": "38f4cae21cef9805e085fb6d21b8108030b4f612",
"short_description": "",
"pubkeys": {
"encryption": {
"key": "399e53e5f0908a33c0857f561d154f2fbafc09c7ae7d6b74da3b40d049c14457",
"signature": "074bb93c0af20ddbe2568f94050429a3c5ca4b3661fa3c5a1c810b5128ed945db0ca9d399bb3f2baec1322e9ff92251d7b21392c5c06f87d4877fa11d606e708"
},
"signing": {
"key": "6a8cbd64631272644503a3dea3f63bd1ef6148de25d1cc0fec38671dfa9c6f1c",
"signature": "70f5e67522bfa6ba56b402e9ea71c50f15c2caf5058fc565c9959ad1427e275c9e5bce18b98444734973c54f02a226d17092a95ac7f1a56e2287c7a996193606"
},
"bitcoin": {
"key": "024febe65c1b237c37394ebfd2d5abc2af564c4a0ca8435a6b3045a4a3e6e7e8d4",
"signature": "3efdc208101d0aee0973ec6f75620ed25fb0873a69299aeee81740172aa7e50a0d68fbfe4bc57874a94d7c8e095ef519ee3d974ad880b9f7f62f0aaac1e7140e"
}
},
"guid": "fa5025f8ac9fcba532cff9608d1c080a84e2f7a1"
}
],
"id": {
"pubkeys": {
"encryption": "9e55643cd11bd1d01915f2de03ea11c80138a2bb4e0b9e04a6e924ca7c6ac76c",
"guid": "318bff260a7cc2133ef59fac40e23d5f1361e111eae78f31f8be154cc5cd88af",
"bitcoin": "0284c670567cd6555c2d5519b74aaade7af3ca2781c6b79db78091b9f0c53939cc"
},
"guid": "a9c6bb758d97b74520008a9f38710f946750516a",
"blockchain_id": "@drwasho"
},
"metadata": {
"category": "service",
"version": "0.1",
"category_sub": "fixed price",
"expiry": "2016-01-25T08:12 UTC"
}
}
}
}
JSON returns the following objects:
- Vendor Offer
- Listing
- Metadata
- Category - [physical item, digital content, service]
- Version - 0.1
- Sub-category - fixed price (will eventually support auctions)
- Expiry - when the contract is no longer valid
- ID
- Pubkeys
- Encryption - communication key
- GUID - public key used to generate GUID
- Bitcoin - multisignature escrow key
- GUID
- Blockchain ID - handle registered to GUID, if any
- Pubkeys
- Item
- Category - user defined product category
- Description - description of the listing
- Price per unit - can be priced in a fiat currency
- Bitcoin
- Title - title of the listing
- Process time - number of days required to confirm whether an order will be accepted or not
- Image hash - SHA256 hashes of images in the listing
- NSFW - is the listing not suitable for work (i.e. 18+)
- Keywords - contract will be searchable on the network by these keywords
- Moderators
- Fee - fee for using services
- Name - name of the node (or user behind the node)
- Blockchain ID
- Avatar
- Short description - short description of services
- Pubkeys - keys and signatures required for proof
- Encryption
- Key
- Signature
- Signing
- Key
- Signature
- Bitcoin
- Key
- Signature
- Encryption
- GUID
- Metadata
- Signature
- Digital signature of
vendor_offer.listing
- Digital signature of
- Listing
<html>
<body>
<form action="http://localhost:18469/api/v1/contracts" method="get" enctype="multipart/form-data" target="_blank">
<input type="text" name="id" placeholder="Contract ID" required /><br><br>
<input type="text" name="guid" placeholder="GUID of target node" /><br><br>
<input type="submit" value="View Contract" />`
</form>
</body>
</html>
API call to cleanly disconnect from connected nodes and shutsdown the OpenBazaar server component.
http://localhost:18469/api/v1/shutdown
None.
None.
<html>
<body>
<form action="http://localhost:18469/api/v1/shutdown" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Shutdown" />`
</form>
</body>
</html>
Retrieves any sales made by the node.
http://localhost:18469/api/v1/get_sales
None.
[{
"status": 0,
"buyer": "@chrispacia",
"description": "Tolstoy's epic masterpiece intertwines the lives of private and public individuals during the time of the Napoleonic wars and the French invasion of Russia. The fortunes of the Rostovs and the Bolkonskys, of Pierre, Natasha, and Andrei, are intimately connected with the national history that is played out in parallel with their lives. Balls and soirees alternate with councils of war and the machinations of statesmen and generals, scenes of violent battles with everyday human passions in a work whose extraordinary imaginative power has never been surpassed. \r\n\r\nThe prodigious cast of characters, seem to act and move as if connected by threads of destiny as the novel relentlessly questions ideas of free will, fate, and providence. Yet Tolstoy's portrayal of marital relations and scenes of domesticity is as truthful and poignant as the grand themes that underlie them.",
"title": "Handbag",
"order_id": "549c844c08048166ed4ac9d44d9bf8916c7ce9cb",
"timestamp": 1449414448.939755,
"btc_total": 0.002,
"contract_type": "physical good",
"thumbnail_hash": "cf344e4dc1eb9c38aff103c18116cd15754ad30f"
}]
<html>
<body>
<form action="http://localhost:18469/api/v1/get_sales" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Sales" />`
</form>
</body>
</html>
Retrieves any purchases made by the node.
http://localhost:18469/api/v1/get_purchases
None.
{
"status": 0,
"contract_type": "digital good",
"vendor": "@themes",
"description": "A beach theme",
"title": "Beach Theme",
"order_id": "8bd10ebab092d0fbf2cec1f2d0ad84dfa0f4f8df",
"timestamp": 1449283905.809595,
"btc_total": 0.005,
"thumbnail_hash": "4cde0fba7feb2f979975e2d4e772198c77807c0b"
}
<html>
<body>
<form action="http://localhost:18469/api/v1/get_purchases" method="get" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Get Sales" />`
</form>
</body>
</html>
I am running locally, but trying to separate the UI and server daemon on different machine. Looks like it didn't even open api port 18469 and ws port 18466 . Did it change in the latest release? Is there any doc to fully customize server settings including file storage, database everything? Ideally I'd like to go them in different drive but by default they all go under C:\User\Appdata