Integration Guide

Sell your first item on the Qost Order Book in 4 steps.

1. Installation

npm install @mysten/sui.js dotenv

2. Initialize Client

const { SuiClient, getFullnodeUrl } = require('@mysten/sui.js/client');
const { Ed25519Keypair } = require('@mysten/sui.js/keypairs/ed25519');

// Connect to Sui Testnet
const client = new SuiClient({ url: getFullnodeUrl('testnet') });
const keypair = Ed25519Keypair.fromSecretKey(process.env.PRIVATE_KEY);

3. Prepare Product Data

Note: Prices are in kobo (1/100 NGN). Provenance data (IMEI) is required.

const productData = {
    name: "iPhone 15 Pro 256GB Black",
    sku: "IPHONE15PRO-256-BLK",
    brand: "Apple",
    pricing: {
        shopper_price: 85000000, // 850,000 NGN
        currency: "NGN"
    },
    provenance: {
        imei: "356938035643809",
        serial: "F2LXH3J5N"
    }
};

4. Submit Transaction

Use the atomic list_product_with_device function to create both the listing and provenance record in one go.

const { TransactionBlock } = require('@mysten/sui.js/transactions');

const tx = new TransactionBlock();
tx.moveCall({
    target: `${PACKAGE_ID}::merchant_actions::list_product_with_device`,
    arguments: [
        tx.object(DEVICE_REGISTRY_ID),
        tx.object(PRODUCT_REGISTRY_ID),
        tx.pure(productData.name),
        // ... mapped arguments (see full reference) ...
        tx.pure(productData.provenance.imei),
        tx.object('0x6') // Clock
    ]
});

const result = await client.signAndExecuteTransactionBlock({
    signer: keypair,
    transactionBlock: tx,
});
console.log("Digest:", result.digest);

Architecture

Qost utilizes a hybrid architecture to ensure both transparency and privacy:

• On-Chain (Sui): Public profiles, product listings, price offers, and device provenance history.
• Off-Chain: Sensitive data (KYC documents, bank details) and high-performance indexing.

Smart Contracts

We deploy a suite of Move modules to handle the core logic:

Authentication

All requests to the Market API require an API Key in the header.

For the hackathon demo, use: qost-hackathon-demo-key

Get Aggregated Listings

Fetch the global order book of available devices. Filter by category, brand, or price.

curl -X GET "https://api.qost.com/v1/market/listings?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

const axios = require('axios');

const response = await axios.get('https://api.qost.com/v1/market/listings', {
    params: { limit: 10 },
    headers: { 'x-api-key': 'YOUR_API_KEY' }
});

console.log(response.data);

import requests

url = "https://api.qost.com/v1/market/listings"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {"limit": 10}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Query Parameters

Get Product Details

Get full specifications and blockchain provenance for a specific listing.

Verify Device Provenance

Verify the history and authenticity of a device using its IMEI. This queries both the Qost database and the Sui Blockchain.

Response Example

{
  "success": true,
  "data": {
    "imei": "356938035643809",
    "status": "LISTED",
    "blockchain_verified": true,
    "device_details": {
      "name": "iPhone 13 Pro Max",
      "condition": "Used - Good"
    },
    "provenance": {
      "origin_region": "UK",
      "import_date": "2025-11-20T08:30:00.000Z"
    }
  }
}

Report Sale (Order Placement)

Notify Qost when a device is sold on your platform. This marks the item as sold in the global order book and transfers ownership on the blockchain.

Request Body

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "sale_price": 450000,
  "buyer_address": "0x123... (Optional)"
}

Submit Product Review

Allow customers to submit reviews for products they've purchased. Reviews help build trust and provide valuable feedback to merchants.

Request Body

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "[email protected]",
  "customer_name": "John Doe",
  "rating": 5,
  "title": "Excellent phone!",
  "comment": "Great condition, fast delivery. Highly recommended!",
  "verified_purchase": true
}

Response Example

{
  "success": true,
  "message": "Review submitted successfully",
  "data": {
    "review_id": "123e4567-e89b-12d3-a456-426614174000",
    "product_name": "iPhone 13 Pro Max",
    "merchant_name": "TechStore Ltd",
    "rating": 5,
    "created_at": "2025-12-10T10:30:00.000Z"
  }
}

Get Product Reviews

Retrieve all reviews for a specific product, including ratings, comments, and merchant responses. Includes comprehensive statistics and rating distribution.

Query Parameters

Response Example

{
  "success": true,
  "data": {
    "reviews": [
      {
        "review_id": "123e4567-e89b-12d3-a456-426614174000",
        "customer_name": "John Doe",
        "rating": 5,
        "title": "Excellent phone!",
        "comment": "Great condition, fast delivery.",
        "verified_purchase": true,
        "merchant_response": "Thank you for the positive feedback!",
        "merchant_response_date": "2025-12-10T11:00:00.000Z",
        "helpful_votes": 3,
        "createdAt": "2025-12-10T10:30:00.000Z"
      }
    ],
    "statistics": {
      "average_rating": "4.2",
      "total_reviews": 15,
      "verified_reviews": 12,
      "rating_distribution": [
        { "rating": 5, "count": 8 },
        { "rating": 4, "count": 4 },
        { "rating": 3, "count": 2 },
        { "rating": 2, "count": 1 },
        { "rating": 1, "count": 0 }
      ]
    }
  }
}

Mark Review as Helpful

Allow users to mark reviews as helpful, which helps surface the most useful reviews to other customers.

Response Example

{
  "success": true,
  "message": "Review marked as helpful",
  "helpful_votes": 4
}

Platform Review Statistics

Get overall review statistics for the entire platform, useful for analytics and reporting.

Response Example

{
  "success": true,
  "data": {
    "total_reviews": 1247,
    "average_rating": "4.3",
    "verified_reviews": 892,
    "responded_reviews": 734,
    "recent_reviews": 89,
    "response_rate": "58.9"
  }
}

Review UI Pages

We also provide ready-to-use HTML pages for customer review interactions:

Plugins & SDKs

No-code integrations for popular e-commerce platforms.

Shopify Integration Beta

Connect your Shopify store to Qost to automatically list products and settle sales on-chain.

1. Install the App

Visit the Qost Merchant Portal settings page to get your unique installation URL.

2. Configure Webhooks

The app automatically registers the following webhooks:

• products/create - Lists new items on Qost
• products/update - Syncs price and inventory changes
• orders/create - Reports sales and removing liquidity

3. Map Provenance Fields

In your Shopify Product settings, add a Metafield definition for custom.imei to track device provenance.

Troubleshooting

Common error codes and how to resolve them.

Smart Contract Errors

Webhook Debugging

• Signature Failures: Ensure you are validating against the rawBody, not the parsed JSON.
• Timeouts: Compute your logic asynchronously. Always return 200 OK immediately upon receipt.