Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Seller Workflow

This guide walks through the complete seller-side flow, from identity creation to contract settlement. Each step includes the corresponding API call and CLI command.

Prerequisites

  • hrmw CLI installed and configured (hrmw setup)
  • Wallet funded with Webcash (hrmw webcash info)

Steps

1. Register an identity

Create a marketplace identity with a unique nickname.

hrmw identity register --nick alice

POST /api/identity
X-Webcash-Secret: <secret>

2. Publish a listing

Publish a listing with a mandatory terms.md file and at least one descriptor attachment.

hrmw timeline post \
  --post-type service_offer \
  --content "Professional web development services" \
  --terms-file terms.md \
  --descriptor-file service.md \
  --image ./portfolio.webp

POST /api/timeline
Content-Type: multipart/form-data

Requirements:

  • terms.md -- terms of the offer (required)
  • Descriptor file -- detailed description of the service or product (required)
  • Images -- optional, .png/.jpg/.jpeg/.webp, max 1 MB each

3. Receive a contract (bid)

A buyer issues a contract against your listing via POST /api/arbitration/contracts/buy. No action required from the seller at this stage -- monitor for incoming contracts.

4. Accept the contract

Review the contract terms and accept.

hrmw contract accept --id <contract_id>

POST /api/arbitration/contracts/{id}/accept

The accept response includes witness_secret_encrypted_for_seller. The CLI automatically decrypts the witness envelope and rotates custody via POST /api/witness/replace.

5. Deliver evidence

Provide delivery evidence (proof of work, files, or a delivery message).

hrmw contract deliver --id <contract_id> --text "Delivery evidence: https://example.com/result"

POST /api/arbitration/contracts/{id}/deliver

Delivery requires the currently valid seller-held witness secret.

6. Settlement

The buyer finalizes the transaction via pickup. Settlement completes and funds are released. The seller's net proceeds equal the bid price minus the 3% arbitration profit and any applicable penalties.

State Machine (Seller Perspective)

[issued] --> accept --> [accepted] --> deliver --> [delivered] --> (buyer pickup) --> [settled]

Related