ordinalsbot marketplace api backend is a Node.js project providing RESTful API endpoints for managing marketplace listings and offers using MongoDB. This project integrates essential middleware, environment variable configurations, and includes detailed API documentation via Swagger UI.
- Configuration
- Installation
- Usage
- API Endpoints
- MongoDB Schema
- Swagger Documentation
- Contributing
- License
Configuration settings are sourced from a .env
file and a config module. Ensure you have the necessary environment variables set up in your .env
file.
-
Clone the repository:
git clone https://github.com/rezzecup/ordinalsbot-marketplace-api-backend.git cd ordinalsbot-marketplace-api-backend
-
Install the dependencies:
npm install
-
Create an
.env
file and add your environment variables:NETWORKTYPE=TESTNET PORT=3000 MONGODB_URI=mongodb://localhost:27017/ordinalsbot
You can reference .env.example file configuration.
-
Start the server:
npm start
After starting the server, the application will be running on the specified port. By default, it is set to port 3000. You can access the backend running status at http://localhost:3000
and see the Swagger API documentation at http://localhost:3000/api-docs
.
The following routes are available in the application:
POST /api/create-listing
: Create a new listing.POST /api/save-listing
: Save listing data.DELETE /api/delete-listing
: Delete an existing listing.PUT /api/update-listing
: Update an existing listing.POST /api/create-offer
: Create a new offer for a listing.POST /api/submit-offer
: Submit an offer for a listing.
The MongoDB schema used in this project is as follows:
import mongoose from "mongoose";
const OrderSchema = new mongoose.Schema({
ordinalId: { type: String, required: true, unique: true },
price: { type: Number, required: true },
sellerPaymentAddress: { type: String, required: true },
sellerOrdinalPublicKey: { type: String, required: true },
status: { type: String, required: true },
ordinalUtxoTxId: { type: String, required: true },
ordinalUtxoVout: { type: Number, requred: true },
serviceFee: { type: Number },
signedListingPSBT: { type: String, required: true },
});
const OrderModel = mongoose.model("order", OrderSchema);
export default OrderModel;
Swagger UI is integrated to provide an interactive API documentation. You can access it at http://localhost:3000/api-docs
. This documentation will dynamically reflect the API endpoints of the application.
Contributions are welcome! Please follow these steps:
- Fork the repository.
- Create a new branch (
git checkout -b feature-branch
). - Commit your changes (
git commit -m "Add new feature"
). - Push your branch (
git push origin feature-branch
). - Create a new Pull Request.
This project is licensed under the MIT License.
- Listing: Operations related to managing listings on the marketplace
- Offer: Operations related to making offers and purchasing ordinals
- Endpoint:
/create-listing
- Method: POST
- Summary: This endpoint lists one or more ordinals for sale on the marketplace.
- Description: This endpoint is used to list ordinals for sale. It returns a Partially Signed Bitcoin Transaction (PSBT) which the owner must sign. The buyer must provide the unspent transaction output (UTXO) covering the price and fees, with the seller's signature required only during the initial listing.
- RequestBody:
- Content Type:
application/json
- Schema:
CreateListing
- Content Type:
- Responses:
- 200: Create Listing Success!
- 500: Create Listing failed!
- Endpoint:
/save-listing
- Method: POST
- Summary: Save listing is part of the create listing process.
- Description: After receiving a PSBT from the
create-listing
endpoint, this signed PSBT must be saved in the listing database through this endpoint. - RequestBody:
- Content Type:
application/json
- Schema:
SaveListing
- Content Type:
- Responses:
- 200: Save Listing Success!
- 500: Save Listing failed!
- Endpoint:
/relist
- Method: POST
- Summary: Update an existing marketplace listing with a new price.
- Description: This endpoint updates an existing listing with a new price and returns a PSBT needing the seller's signature. The signed PSBT must be confirmed via
/marketplace/confirm-relist
for the changes to take effect. - RequestBody:
- Content Type:
application/json
- Schema:
UpdateListing
- Content Type:
- Responses:
- 200: Update Listing Request Success!
- 500: Update Listing Request failed!
- Endpoint:
/confirm-relist
- Method: POST
- Summary: Confirm the updated marketplace listing.
- Description: Confirms the price update to an existing listing. Returns a PSBT which must be signed and returned to
/marketplace/confirm-relist
. - RequestBody:
- Content Type:
application/json
- Schema:
ConfirmUpdateListing
- Content Type:
- Responses:
- 200: Delete Listing Success!
- 500: Delete Listing failed!
- Endpoint:
/delist
- Method: POST
- Summary: Delete an existing marketplace listing.
- Description: Deletes an ordinal listing from the marketplace. The process involves creating and signing a transaction, which is then confirmed via
/confirm-delist
to transfer the ordinal back to the seller. - RequestBody:
- Content Type:
application/json
- Schema:
DeleteListing
- Content Type:
- Responses:
- 200: Update Listing Success!
- 500: Update Listing failed!
- Endpoint:
/create-offer
- Method: POST
- Summary: Create a transaction to purchase an ordinal listed for sale.
- Description: Generates a PSBT to be signed by the potential buyer. A platform fee of 1% is applied only upon the sale.
- RequestBody:
- Content Type:
application/json
- Schema:
CreateOffer
- Content Type:
- Responses:
- 200: Create Offer Success!
- 500: Create Offer failed!
- Endpoint:
/submit-offer
- Method: POST
- Summary: Complete the purchase of an ordinal.
- Description: Submits a signed PSBT to complete the purchase. A platform fee of 1% is applied to the seller upon a successful sale.
- RequestBody:
- Content Type:
application/json
- Schema:
SubmitOffer
- Content Type:
- Responses:
- 200: Submit Offer Success!
- 500: Submit Offer failed!