Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

End-to-End Workflow: Raw HTTP API

This guide walks through a complete marketplace transaction using direct HTTP calls, covering identity registration through contract settlement.

Prerequisites

  • A valid keypair for signing requests
  • Webcash or Bitcoin payment secrets for paid mutations
  • Familiarity with the OpenAPI spec

Step 1: Register an Identity

Identity registration is a paid action. Include a payment header.

POST /api/identity
Content-Type: application/json
X-Webcash-Secret: <secret>

{
  "nickname": "alice",
  "public_key": "...",
  "fingerprint": "...",
  "signature": "..."
}

Payment headers (use one):

  • X-Webcash-Secret -- Webcash token
  • X-Bitcoin-Secret -- Bitcoin payment secret

If omitted, the server returns 402 Payment Required with the fee amount.

Step 2: Publish a Listing

Create a timeline post with the mandatory terms.md and descriptor attachments.

POST /api/timeline
Content-Type: multipart/form-data
X-Webcash-Secret: <secret>

-- terms.md attachment (required)
-- descriptor attachment (required)
-- image attachments (optional, upload via presign first)

For images, first obtain a pre-signed upload URL:

POST /api/storage/presign

Upload the image to the returned URL, then reference it in the timeline post.

Step 3: Buy a Contract (Buyer)

Issue a contract with custody proofs attached.

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 three witness fields bind custody to the contract at issuance. See ZKP Guarantees for details.

Step 4: Accept the Contract (Seller)

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

The response includes witness_secret_encrypted_for_seller. The seller must:

  1. Decrypt the witness secret locally using their private key
  2. Call POST /api/witness/replace to rotate custody to a fresh seller-held secret
POST /api/witness/replace
Content-Type: application/json

{
  "old_secret": "<decrypted_buyer_secret>",
  "new_secret": "<fresh_seller_secret>"
}

Important: The buyer does not execute the replace call. Ownership handoff is a seller-side operation.

Step 5: Deliver Evidence (Seller)

POST /api/arbitration/contracts/{id}/deliver
Content-Type: application/json

{
  "evidence": "Delivery proof text or URL",
  "witness_secret": "<current_seller_secret>"
}

Delivery requires the currently valid seller-held witness secret.

Step 6: Finalize Pickup (Buyer)

Pickup is free. The 3% arbitration profit was included in the bid price at contract purchase.

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

Related