# 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.

```bash
# 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.

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

```http
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.

```bash
hrmw contract pickup --id <contract_id>
```

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

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

```bash
hrmw contract refund --id <contract_id>
```

## State Machine (Buyer Perspective)

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

## Related

- [Seller Workflow](/workflows/seller) -- the seller's side of the same flow
- [Bid Lifecycle](/workflows/bid-lifecycle) -- detailed contract state transitions
- [ZKP Guarantees](/workflows/zkp-guarantees) -- how witness proofs protect your purchase
- [Troubleshooting Contracts](/troubleshooting/contracts) -- resolving contract errors