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.
Follows a target node and will cause you to receive notifications from that node after certain event (e.g. new listing, broadcast messages) and share some metadata (in future).
http://localhost:18469/api/v1/follow
- guid=[target node guid]
- {"success": "true"}
- {"success": "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/follow" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="guid" placeholder="Target Node GUID" /><br><br>
<input type="submit" value="Follow" />`
</form>
</body>
</html>
Stop following a target node, will cease to receive notifications and sharing metadata.
http://localhost:18469/api/v1/unfollow
- guid=[Target node GUID]
- {"success": "true"}
- {"success": "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/unfollow" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="guid" placeholder="Target Node GUID" /><br><br>
<input type="submit" value="Follow" />`
</form>
</body>
</html>
Add data related to the node's profile into the database, which will be visible to other nodes.
http://localhost:18469/api/v1/profile
- name=[user-generated name]
- String
- Required
- Must be set on the firt call to create the profile, but can be omitted on subsequent calls to update other fields in the profile
- location=[country code]
- Required
- Must be set on the firt call to create the profile, but can be omitted on subsequent calls to update other fields in the profile
- Required
- handle=[Blockchain ID handle]
- String starting with
@
- The Blockchain ID handle starting with “@”
- Eventually this will be required to resolve to the guid
- String starting with
- about=[text]
- String
- 'About' text for the store
- short_description=[text]
- String
- Text to show in the homepage store list (string)
- nsfw=[true,false]
- Boolean
- Is this user profile/store nsfw? Will default to false if the field is omitted. (“true” or “false”)
- vendor=[true,false]
- Boolean
- Is this user a vendor? must be set to true if so. defaults to false if omitted. (“true” or “false”)
- moderator=[true,false]
- Boolean
- Is this user a moderator? must be set to true if so. defaults to false if omitted. (“true” or “false”)
- website=[URL]
- String
- A website for this user (string)
- email=[email address]
- String
- An email address for this user (string)
- primary_color=[number]
- Integer
- Hex color formatted in base 10. For example, 00FF00 should be sent as “65280” (string of base 10 formatted hex color)
- secondary_color=[number]
- Integer
- Same as primary color
- text_color=[number]
- Integer
- Same as primary color
- background_color=[number]
- INteger
- Same as primary color
- avatar=[image hash]
- String
- The hash of the avatar image. must have been previously uploaded using the upload_image api call (40 character hex string)
- header=[image hash]
- String
- The hash of the header image. must have been previously uploaded using the upload_image api call. (40 character hex string)
- pgp_key=[public key block]
- String
- A pgp public key to include in the profile. if included the signature field must also be included. (string pgp public key block)
- {"success": "true"}
- {"success": "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/profile" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="name" placeholder="Name" required /><br><br>
<input type="text" name="location" placeholder="Location" required /><br><br>
<input type="text" name="handle" placeholder="Blockchain ID Handle" /><br><br>
<input type="text" name="about" placeholder="About Text" /><br><br>
<input type="text" name="short_description" placeholder="Short Description Text" /><br><br>
<input type="text" name="nsfw" placeholder="NSFW? True or False" /><br><br>
<input type="text" name="vendor" placeholder="Vendor? True or False" /><br><br>
<input type="text" name="moderator" placeholder="Moderator? True or False." /><br><br>
<input type="text" name="website" placeholder="Website" /><br><br>
<input type="text" name="email" placeholder="Email" /><br><br>
<input type="number" name="primary_color" placeholder="Primary color hex (base 10; e.g. 65280)" /><br><br>
<input type="number" name="secondary_color" placeholder="Secondary color hex (base 10; e.g. 65280)" /><br><br>
<input type="number" name="background_color" placeholder="Background color hex (base 10; e.g. 65280)" /><br><br>
<input type="text" name="avatar" placeholder="Avatar image hash" /><br><br>
<input type="text" name="header" placeholder="Header image hash" /><br><br>
<input type="text" name="pgp_key" placeholder="PGP public key" /><br><br>
<input type="submit" value="Submit Profile Data" />`
</form>
</body>
</html>
Adds a social account to the user profile data of the user.
http://localhost:18469/api/v1/social_accounts
- account_type=[social account]
- Required
- String
- Options (must be one of these; case sensitive):
- snapchat
- username=[username]
- Required
- String
- proof=[URL]
- URL proving ownership of the social account
- Presently not validated
- {"success": "true"}
- {"success": "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/social_accounts" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="account_type" placeholder="Account type" required /><br><br>
<input type="text" name="username" placeholder="Account username" required /><br><br>
<input type="text" name="proof" placeholder="URL proof of ownership" /><br><br>
<input type="submit" value="Add Social Account" />`
</form>
</body>
</html>
Sets your node as a Moderator, which is discoverable on the network.
http://localhost:18469/api/v1/make_moderator
None.
- {"success": "true"}
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/make_moderator" method="post" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Become a Moderator" />`
</form>
</body>
</html>
Removes the node as a Moderator and is no longer discoverable on the network as a Moderator.
http://localhost:18469/api/v1/unmake_moderator
None.
- {"success": "true"}
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/unmake_moderator" method="post" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Stop being a Moderator" />`
</form>
</body>
</html>
Creates a listing contract, which is saved to the database and local file system, as well as publish the keywords in the distributed hash table.
http://localhost:18469/api/v1/contracts
- expiration_date=[UTC]
- Sormatted string
- The date the contract should expire in string formatted UTC datetime
- Example:
- "2015-11-01T00:00 UTC"
- “” if the contract never expires
- metadata_category=[category]
- Formatted string
- Select from:
- physical good
- digital good
- service
- title=[title text]
- String
- Title of the product for sale
- description=[description text]
- String
- Description of the item, content or service
- currency_code=[code]
- Formatted string
- The currency the product is priced in. may either be “btc” or a currency from this list
- price=[value]
- String
- The price per unit in the same currency as
currency_code
.
- process_time=[time]
- String
- The time it will take to prepare the item for shipping
- nsfw=[true/false]
- Boolean
- Is the item not suitable for work (i.e. 18+)
- shipping_origin=[country/region]
- Formatted string
- Required and only applicable if the
metadata_category
is a physical good - Where the item ships from
- Must be a formatted string from this list
- shipping_regions=[locations]
- Formatted string
- Required and only applicable if the
metadata_category
is a physical good - A list of countries/regions where the product will ship to
- Each item in the list must be formatted from this list
- est_delivery_domestic=[time]
- Estimated delivery time for domestic shipments
- est_delivery_international=[time]
- String
- Estimated delivery time for international shipments
- terms_conditions=[terms and conditions text]
- String
- Any terms or conditions the user wishes to include
- returns=[returns policy text]
- String
- Return policy
- shipping_currency_code=[currency code]
- Formatted string
- The currency code used to price shipping. may either be “btc” or a currency from this list
- shipping_domestic=[price]
- String
- The price of domestic shipping in the selected
currency code
- shipping_international=[price]
- String
- The price of nternational shipping in the selected
currency code
- keywords=[keyword text]
- String
- A list of string search terms for the listing
- Must be fewer than 10
- category=[category text]
- Sting
- A user-generated category for this product
- Will show in store’s category list
- condition=[condition text]
- The condition of the product
- sku=[sku text]
- String
- Stock keeping unit (sku) for the listing
- images=[image hash]
- 40 character hex string
- A list of SHA256 image hashes
- The images should be uploaded using the
upload_image
api call
- free_shipping=[boolean]
- "true" or "false"
- moderators=[guids]
- GUID: 40 character hex string
- A list of moderator GUIDs that the vendor wishes to use
- Note: the moderator must have been previously returned by the
get_moderators
websocket call. - Given the UI workflow, this call should always be made before the contract is set.
- options=[options text]
- String
- A list of options for the product
- Example: “size”, “color”
- option=[option text]
- String
- For each option in the options list, another argument should be added using that option name and a list of value
- For example, given “color” in the options list, choose from "red", "green", "purple" etc
- {"id": "", "success": true}
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/contracts" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="title" placeholder="Title" required/><br><br>
<input type="text" name="description" placeholder="Description" required /><br><br>
<input type="text" name="currency_code" placeholder="Currency Code" required /><br><br>
<input type="text" name="price" placeholder="Price" required /><br><br>
<input type="text" name="process_time" placeholder="Process Time" /><br><br>
<input type="text" name="nsfw" placeholder="Not suitable for work?" /><br><br>
<input type="text" name="keywords" placeholder="Keywords" /><br><br>
<input type="text" name="category" placeholder="Category" /><br><br>
<input type="text" name="condition" placeholder="Condition of the item" /><br><br>
<input type="text" name="sku" placeholder="SKU" /><br><br>
<input type="text" name="images" placeholder="Image hashes" /><br><br>
<input type="text" name="moderators" placeholder="Moderator GUIDs" /><br><br>
<input type="text" name="options" placeholder="Listing Options" /><br><br>
<input type="text" name="expiration_date" placeholder="Expiration date for the listing" /><br><br>
<input type="text" name="metadata_category" placeholder="Physical item, digital content, or service." /><br><br>
<input type="text" name="free_shipping" placeholder="Free shipping?" /><br><br>
<input type="text" name="shipping_origin" placeholder="Shipping origin" /><br><br>
<input type="text" name="shipping_regions" placeholder="Shipping Regions" /><br><br>
<input type="text" name="est_delivery_domestic" placeholder="Estimated delivery time for domestic deliveries." /><br><br>
<input type="text" name="est_delivery-international" placeholder="Estimated delivery time for international deliveries." /><br><br>
<input type="text" name="shipping_domestic" placeholder="Price for domestic shipping" /><br><br>
<input type="text" name="shipping_international" placeholder="Price for international shipping" /><br><br>
<input type="text" name="terms_conditions" placeholder="Terms and Conditions of sale." /><br><br>
<input type="text" name="returns" placeholder="Returns policy for the listing." /><br><br>
<input type="submit" value="Create Listing" />
</form>
</body>
</html>
Purchases a contract by sending the purchase into the Vendor. The Buyer waits for a response to indicate whether the purchase is successful or not. If successful, the Buyer needs to fund the direct or multisig address.
http://localhost:18469/api/v1/purchase_contract
- id=[contract id]
- 40 character hex string
- The contract id to be purchased
- Note: the contract must be in cache, meaning it must have been called specifically at least once.
- quantity=[quantity]
- String
- Number of items to be purchased
- ship_to=[name]
- String
- Name of the person that the item will be shipped to
- address=[street address]
- String
- Street address for delivery of the item
- city=[name of city]
- String
- Name of the city corresponding to the address
- state=[name of state]
- String
- Name of the state corresponding to the address
- postal_code=[postcode of the delivery address]
- String
- Postal code corresponding to the address
- moderator=[GUID]
- 40 character hex string
- The Moderator, listed in the original contract, chosen by the buyer
- This is omitted if there is a direct payment
- options=[options for the listing]
- String
- E.g. "color"
- option=[option from options]
- String
- E.g. "red"
{
"success" : true,
"address" : "bitcoin address to fund",
"amount" : "amount to fund",
"order_id" : "purchase order id"
}
<html>
<body>
<form action="http://localhost:18469/api/v1/purchase_contract" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="id" placeholder="Contract ID" /><br><br>
<input type="text" name="quantity" placeholder="Quantity" /><br><br>
<input type="text" name="ship_to" placeholder="Name of recipient" /><br><br>
<input type="text" name="address" placeholder="Street Address" /><br><br>
<input type="text" name="city" placeholder="City" /><br><br>
<input type="text" name="state" placeholder="State" /><br><br>
<input type="text" name="postal_code" placeholder="Postcode" /><br><br>
<input type="text" name="moderator" placeholder="Moderator GUID" /><br><br>
<input type="text" name="options" placeholder="Option" /><br><br>
<input type="submit" value="Place Order" />`
</form>
</body>
</html>
Sends the order confirmation and shipping information to the Buyer. If he’s offline, it will embed this data into the dht. The API call also updates the status of the order in the database.
http://localhost:18469/api/v1/confirm_order
- id=[order id]
- 40 character hex string
- ID of the order placed by the Buyer
- This only applies to orders that have been funded
- shipper=[name of shipper]
- String
- For physical goods to be delivered
- tracking_number=[shipping tracking number]
- String
- For physical goods to be delivered
- est_delivery=[estimated delivery of item]
- String
- Based on the feedback from the shipper, an up to date estimate of delivery.
- url=[link to digital content]
- Formatted string
- For digital content only
- password=[password to access digital content]
- String
- To decrypt and/or access protected digital content
- {"success" : "true"}
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/confirm_order" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="id" placeholder="Purchase order ID" required /><br><br>
<input type="text" name="shipper" placeholder="Name of the Shipper" /><br><br>
<input type="text" name="tracking_number" placeholder="Shuipping tracking number" /><br><br>
<input type="text" name="est_delivery" placeholder="Estimated delivery time" /><br><br>
<input type="text" name="url" placeholder="URL to digital content" /><br><br>
<input type="text" name="password" placeholder="Password to access digital content" /><br><br>
<input type="submit" value="Confirm Order" />`
</form>
</body>
</html>
Sends a message with a partially signed transaction releasing funds from escrow to the Vendor as well as review data.
http://localhost:18469/api/v1/complete_order
- id=[order id]
- 40 character hex string
- feedback=[feedback rating]
- String: 1-5
- Overall rating of the transaction
- quality=[item quality rating]
- String: 1-5
- Rating of the quality of the item, content, or service
- description=[item description rating]
- String: 1-5
- Rating of the listing description of the item, content, or service
- delivery_time=[delivery time rating]
- String: 1-5
- Rating of the time taken to deliver the item
- customer_service=[customer service rating]
- String: 1-5
- Rating of the customer service displayed by the Vendor
- review=[free form review text]
- String (<= 80 characters)
- Free text to review the transaction
- {"success" : "true" }
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/complete_order" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="id" placeholder="Order ID" required /><br><br>
<input type="text" name="feedback" placeholder="Feedback Rating" /><br><br>
<input type="text" name="quality" placeholder="Item Quality Rating" /><br><br>
<input type="text" name="description" placeholder="Listing Description Rating" /><br><br>
<input type="text" name="delivery_time" placeholder="Delivery Time Rating" /><br><br>
<input type="text" name="customer_service" placeholder="Customer Service Rating" /><br><br>
<input type="text" name="review" placeholder="Review" /><br><br>
<input type="submit" value="Confirm Order" />`
</form>
</body>
</html>
@POST('^/api/v1/upload_image')
arguments:
image= a list of product images to upload (LIST of images in base64. data only, no base64 prefix)
avatar= use this if uploading an avatar image (base64 image)
header= use this if uploading a header image (base64 image)
action:
saves the image in the file system and a pointer to it in the db
return:
{success: True, image_hashes: [list_of_image_hashes]}
http://localhost:18469/api/v1/upload_image
- image=[base 64 image data]
- Base 64, no prefix
- avatar=[base 64 image data]
- Base 64, no prefix
- Use if uploading an avatar image
- header=[base 64 image data]
- Base 64, no prefix
- Use if uploading a store header image
- {"success" : "true", "image_hashes" : [list_of_image_hashes] }
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/upload_image" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="image" placeholder="Base64 Image" /><br><br>
<input type="text" name="avatar" placeholder="Base64 Avatar Image" /><br><br>
<input type="text" name="header" placeholder="Base64 Header Image" /><br><br>
<input type="submit" value="Upload Images" />`
</form>
</body>
</html>
Changes the settings of the node and pushes them to the database.
http://localhost:18469/api/v1/settings
All fields are required.
- refund_address=[bitcoin address]
- String
- If a transaction is refunded, bitcoins will be sent to this address
- currency_code=[currency]
- Formatted string
- Sets the price of listings displayed in the client
- country=[country]
- Formatted string
- Sets the country of origin
- language=[language]
- String
- Language used in the client
- time_zome=[time zone]
- String
- Timezone of the user
- notifications=[true, false]
- Boolean
- Whether notifications are shown in the client
- shipping_addresses=[address list]
- String
- Will be used to determine if an item can be shipped to the user's location
- blocked=[GUIDs]
- 40 character hex string
- Nodes that the user will not retrieve and display data from
- libbitcoin_server=[server URL]
- URL string
- If blank, it will default to the hardcoded libbitcoin servers in the server repository
- ssl=[true, false]
- Boolean
- Sets whether SSL is used to communicate with the server
- terms_conditions=[terms and conditions text]
- String
- Terms and conditions to be added by default to all listings, unless overwritten in the listing process
- refund_policy=[refund policy text]
- String
- Refund policy to be added by default to all listings, unless overwritten in the listing process
- {"success" : "true"}
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/settings" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="refund_address" placeholder="Bitcoin Refund Address" required /><br><br>
<input type="text" name="currency_code" placeholder="Currency Code" required /><br><br>
<input type="text" name="country" placeholder="Country" required /><br><br>
<input type="text" name="language" placeholder="Language" required /><br><br>
<input type="text" name="time_zone" placeholder="Time Zone" required /><br><br>
<input type="text" name="notifications" placeholder="Notifications (true/false)" required /><br><br>
<input type="text" name="shipping_addresses" placeholder="Shipping Addresses" required /><br><br>
<input type="text" name="blocked" placeholder="Blocked Nodes (GUID)" required /><br><br>
<input type="text" name="libbitcoin_server" placeholder="Libbitcoin Server URL" required /><br><br>
<input type="text" name="ssl" placeholder="SSL (true/false)" required /><br><br>
<input type="text" name="terms_conditions" placeholder="Terms and Conditions" required /><br><br>
<input type="text" name="refund_policy" placeholder="Refund Policy" required /><br><br>
<input type="submit" value="Change Settings" />`
</form>
</body>
</html>
Marks a notification as read in the database.
http://localhost:18469/api/v1/mark_notification_as_read
- id=[id of the notification]
- 40 character hex string
- Every notification has an ID that must be referenced in order to mark as read
- {"success" : "true"}
<html>
<body>
<form action="http://localhost:18469/api/v1/mark_notification_as_read" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="id" placeholder="Notification ID" /><br><br>
<input type="submit" value="Mark As Read" />`
</form>
</body>
</html>
Marks all chat messages with a specific node as read in the database.
- guid=[guid of node]
- 40 character hex string
- GUID of the party you are chatting with
- {"success" : "true"}
<html>
<body>
<form action="http://localhost:18469/api/v1/mark_chat_as_read" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="guid" placeholder="GUID" /><br><br>
<input type="submit" value="Mark Chat As Read" />`
</form>
</body>
</html>
Sends a Twitter-like message to all nodes that are following you.
http://localhost:18469/api/v1/broadcast
- message=[message to send]
- String
- 140 characters or less
- {"success" : "true", "peers_reached" : [number reached] }
<html>
<body>
<form action="http://localhost:18469/api/v1/broadcast" method="post" enctype="multipart/form-data" target="_blank">
<input type="text" name="message" placeholder="Message" /><br><br>
<input type="submit" value="Broadcast Message to Followers" />`
</form>
</body>
</html>
Sends a Twitter-like message to all nodes that are following you.
http://localhost:18469/api/v1/check_for_payment
None.
- {"success" : "true"}
- {"success" : "false"}
<html>
<body>
<form action="http://localhost:18469/api/v1/check_for_payment" method="post" enctype="multipart/form-data" target="_blank">
<input type="submit" value="Check for Payment" />`
</form>
</body>
</html>