Marketplace API Reference

Version: 1.0 Date: 2026-04-06 Canister: marketplace Staging Canister ID: h4ci3-hqaaa-aaaao-a7fka-caiCandid Interface: marketplace.did

---

Overview

The marketplace canister provides a vendor registry, product listings, and payment routing with fee-based DOM token burns. Marketplace burns use the HeldBurn system — tokens are held for a 30-day dispute window before being permanently destroyed.

Key Features

• Vendor Registry: Register and manage cooperative vendors
• Product Listings: Create and query product/service listings
• Payment Routing: Route payments with automatic DOM burn fee
• Tiered Burn Rates: 5% (Under50k) or 7% (Over50k) based on USD transaction value
• HeldBurn Disputes: Marketplace burns held 30 days; refundable within window if disputed
• Membership Gating: Vendor registration requires active SBT

Burn Policy

Transaction USD Value	DOM Burn Policy	Burn Rate	Immediate?
< $50,000	MarketplaceUnder50k	5%	No — held 30 days
≥ $50,000	MarketplaceOver50k	7%	No — held 30 days

---

Authentication

Update methods use ic_cdk::caller(). All query methods are public.

Access Levels

Level	Who
Public	Query endpoints
Active Member	Vendor registration, product creation, purchases
Vendor	Manage own listings
Admin	Canister configuration

---

Data Types

Vendor

type Vendor = record {
    id           : nat64;
    principal    : principal;
    name         : text;
    description  : text;
    contact      : text;
    registered_at : nat64;    // nanoseconds
    active       : bool;
};

Product

type Product = record {
    id          : nat64;
    vendor_id   : nat64;
    name        : text;
    description : text;
    price_dom   : nat;          // price in smallest DOM units
    price_usd   : opt float64;  // USD equivalent (oracle-provided)
    active      : bool;
    created_at  : nat64;        // nanoseconds
};

Transaction

type Transaction = record {
    id           : nat64;
    product_id   : nat64;
    buyer        : principal;
    seller       : principal;
    amount_dom   : nat;
    usd_value    : opt float64;
    burn_tx      : opt nat64;   // dom-token HeldBurn ID
    completed_at : nat64;       // nanoseconds
};

---

Query Methods

list_vendors

List all registered vendors.

Signature:

list_vendors : () -> (vec Vendor) query;

Access: Public

Returns: All active vendors ordered by registration date

Example:

const vendors = await marketplace.list_vendors();
vendors.forEach(v => console.log(`${v.id}: ${v.name}`));

---

get_vendor

Fetch a single vendor by ID.

Signature:

get_vendor : (id : nat64) -> (opt Vendor) query;

Access: Public

Parameters:

• id: Vendor ID

Returns: opt Vendor — Some(vendor) if found, None if not

Example:

const vendor = await marketplace.get_vendor(1n);
if (vendor.length > 0) {
  console.log(vendor[0].name);
}

---

list_products

List all active product listings.

Signature:

list_products : () -> (vec Product) query;

Access: Public

Returns: All active products ordered by creation date

Example:

const products = await marketplace.list_products();
products.forEach(p => {
  const price = Number(p.price_dom) / 1e8;
  console.log(`${p.name}: ${price.toFixed(2)} DOM`);
});

---

get_product

Fetch a single product by ID.

Signature:

get_product : (id : nat64) -> (opt Product) query;

Access: Public

Parameters:

• id: Product ID

Returns: opt Product

Example:

const product = await marketplace.get_product(42n);

---

list_transactions

Paginated transaction history.

Signature:

list_transactions : (limit : nat32, offset : nat32) -> (vec Transaction) query;

Access: Public

Parameters:

• limit: Maximum number of records to return (max 100)
• offset: Number of records to skip (for pagination)

Returns: Transactions ordered newest-first

Example:

// First page
const page1 = await marketplace.list_transactions(20, 0);

// Second page
const page2 = await marketplace.list_transactions(20, 20);

---

Update Methods

register_vendor

Register a new vendor. Caller must hold an active SBT.

Signature:

register_vendor : (name : text, description : text, contact : text) -> (variant { Ok : nat64; Err : text });

Access: Active members only

Returns: Result<nat64, text> — New vendor ID on success

Errors:

{ Err: "Active membership required" }
{ Err: "Vendor already registered for this principal" }

---

create_product

Create a new product listing. Caller must be a registered vendor.

Signature:

create_product : (name : text, description : text, price_dom : nat) -> (variant { Ok : nat64; Err : text });

Access: Registered vendors only

Returns: Result<nat64, text> — New product ID on success

---

purchase_product

Purchase a product. Triggers DOM transfer and HeldBurn fee.

Signature:

purchase_product : (product_id : nat64) -> (variant { Ok : nat64; Err : text });

Access: Active members only

Returns: Result<nat64, text> — Transaction ID on success

Flow:

1. Verify buyer has active SBT
2. Fetch product price and vendor
3. Transfer DOM from buyer to vendor via dom-token.icrc1_transfer
4. Calculate burn fee based on USD value (5% or 7%)
5. Call dom-token.burn_with_policy(fee, MarketplaceUnder50k | MarketplaceOver50k) — creates HeldBurn
6. Record transaction
7. Return transaction ID

Note: The burn is held for 30 days. If the buyer opens a dispute and it is upheld, the admin can call dom-token.refund_held_burn(burn_id).

---

Error Handling

Error	Cause
"Active membership required"	Caller does not hold an active SBT
"Vendor already registered"	Principal already has a vendor record
"Product not found"	Invalid product ID
"Insufficient balance"	Buyer lacks DOM for purchase
"Product not active"	Listing has been deactivated

---

Frontend Integration

import { Actor, HttpAgent } from '@dfinity/agent';

const agent = new HttpAgent({ host: 'https://ic0.app' });
const marketplace = Actor.createActor(idlFactory, {
  agent,
  canisterId: 'h4ci3-hqaaa-aaaao-a7fka-cai',
});

// Browse products
async function browseProducts() {
  const products = await marketplace.list_products();
  return products.map(p => ({
    id: p.id,
    name: p.name,
    priceDOM: Number(p.price_dom) / 1e8,
  }));
}

// Paginated transaction history
async function getTransactions(page: number, pageSize = 20) {
  return marketplace.list_transactions(pageSize, page * pageSize);
}

---

Related Documentation

• DOM Token API — HeldBurn
• Inter-Canister Communication
• Membership API (TODO)

---

Changelog

Version 1.0 (2026-04-06)

• Initial API documentation
• Query endpoints: list_vendors, get_vendor, list_products, get_product, list_transactions
• Update endpoints: register_vendor, create_product, purchase_product
• HeldBurn dispute window behavior documented
• Frontend integration example included

---

Last Updated: 2026-04-06 API Version: 1.0 Maintainer: API Team