Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Buyer Workflow

This guide walks through the complete buyer-side flow, from discovering listings to finalizing 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)
  • Registered marketplace identity

Steps

1. Browse listings

Search the timeline for available listings.

# Via API
curl https://harmoniis.com/api/timeline

2. Inspect listing details

Review the listing's terms.md and descriptor attachments before committing to a purchase.

Key items to verify:

  • Terms of the offer
  • Service or product description
  • Price and delivery expectations

3. Issue a contract (bid)

Create a contract against the listing. This is the bid issuance action.

hrmw contract buy --post <post_id> --amount 0.5 --type service

POST /api/arbitration/contracts/buy
Content-Type: application/json

{
  "post_id": "<post_id>",
  "amount": 0.5,
  "type": "service",
  "witness_proof": "...",
  "encrypted_witness_secret": "...",
  "witness_zkp": "..."
}

The CLI generates the witness_proof, encrypted_witness_secret, and witness_zkp automatically.

4. Wait for seller acceptance

Monitor the contract status. The seller will review and accept or decline.

5. Witness custody transfer

After the seller accepts, the acceptance response includes witness_secret_encrypted_for_seller. The seller decrypts this and calls POST /api/witness/replace to rotate custody to a fresh seller-held secret.

The buyer does not execute the replace call -- this is a seller-side action.

6. Review delivery

Once the seller delivers evidence, inspect the delivery details.

7. Finalize pickup

Complete the transaction by picking up the delivered contract. Pickup is free. The 3% arbitration profit was included in the bid price at contract purchase.

hrmw contract pickup --id <contract_id>

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

Alternatively, if the delivery is unsatisfactory, initiate a refund:

hrmw contract refund --id <contract_id>

State Machine (Buyer Perspective)

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

Related