---
title: User Guide
tags: [usage, role/buyer]
audience: Buyer
created: 2026-05-23
---

# User Guide (Buyer)

End-to-end usage of the Amn marketplace for a **Buyer** — the person who creates purchase requests and pays sellers via crypto escrow.

> [!info]
> Looking for a different role? See [[Seller Guide]], [[Admin Guide]], [[Support Guide]].

---

## 1. Creating your account

### 1.1 Sign up

1. Visit **`/auth/jwt/sign-up`**.
2. Enter:
   - **Email** (will receive a verification code)
   - **Password** (≥ 8 chars; mix of letters/digits/symbol recommended)
   - **Role**: choose **Buyer**. (You can later add Seller capabilities — see [[Seller Guide]].)
3. Optional: enter a **referral code** if a friend invited you (you'll both earn points — see [[Referral Flow]]).
4. Accept Terms of Service.
5. Click **Sign up** → you'll receive an email with a 6-digit code.

> [!warning]
> Codes expire in 1 hour. If yours expires, click **Resend code** on the verify page.

Alternative sign-up methods:

- **Sign in with Google** — single-click using your Google account ([[Google OAuth Flow]]).
- **Passkey / Touch ID / Face ID** — passwordless after first sign-up ([[Passkey (WebAuthn) Flow]]).

### 1.2 Verify your email

1. Open the verification email and copy the 6-digit code.
2. Paste into the **Verify** page (`/auth/jwt/verify`).
3. Click **Verify**.
4. You land on the dashboard.

> [!tip]
> Until verified, a yellow banner appears on every page asking you to verify. Some actions (paying, opening disputes) are gated behind email verification.

### 1.3 Complete your profile

Go to **Dashboard → Account → Profile** and fill in:

| Field | Why it matters |
|---|---|
| Display name | Shown to sellers in chat / on offers |
| Avatar | Helps sellers recognize repeat buyers |
| Phone number | Used for delivery coordination (optional) |
| Country / Language | Sets default currency display & language |

---

## 2. Adding addresses

Delivery addresses are required before some sellers will accept your offer.

1. **Dashboard → Account → Address**.
2. Click **+ Add address**.
3. Fill in: label (Home, Office, …), recipient name, country, full address, postal code, phone.
4. Set one as **Primary** — it will be auto-filled into new purchase requests.
5. You can add up to **N** addresses (depending on tier).

---

## 3. Connecting a wallet

If you want to pay via **Web3** instead of SHKeeper invoice:

1. **Dashboard → Account → Wallet**.
2. Click **Connect Wallet**.
3. Choose **MetaMask** (browser) or **WalletConnect** (mobile).
4. Approve the connection request in your wallet.
5. The connected address appears as a chip. You can disconnect anytime.

> [!info]
> Connecting a wallet is **optional**. SHKeeper QR payments work without one. See [[Payment Flow - DePay & Web3]].

---

## 4. Setting up Passkeys (recommended)

1. **Dashboard → Account → Passkey**.
2. Click **Add passkey**.
3. Follow your device's prompt (Touch ID, Face ID, Windows Hello, USB key…).
4. Name the passkey ("MacBook", "iPhone 15", …) and save.
5. Next sign-in, you'll see a **Sign in with passkey** button.

Multiple passkeys can be added — one per device.

---

## 5. Browsing the marketplace

| Where | What you see |
|---|---|
| **`/shop`** | Public list of sellers & featured items |
| **`/shop/[seller]`** | A specific seller's shop |
| **`/shop/[seller]/[id]`** | An item / request template detail |
| **`/post`** | Blog posts (announcements, tutorials) |
| **Dashboard → Overview** | Your personalised dashboard |

---

## 6. Creating a Purchase Request

A **Purchase Request** is a description of what you want to buy. Sellers see open requests and submit offers.

### 6.1 From scratch

1. **Dashboard → Request → + New Request**.
2. Fill in the multi-step form:
   - **Step 1 — Basics**: title, category, sub-category.
   - **Step 2 — Details**: rich description (use the editor — markdown, images), budget range, currency.
   - **Step 3 — Delivery**: pick an address, preferred delivery date.
   - **Step 4 — Attachments**: upload reference photos, spec sheets (max 5 MB each).
   - **Step 5 — Visibility**: public (any seller can offer) or invite-only (specific sellers).
3. Click **Save as draft** to come back later, or **Publish** to make it live.

> [!tip]
> Use the **AI-assist** button next to the description field — it suggests phrasing improvements (uses OpenAI). See [[AI API]].

### 6.2 From a template

If a seller shared a request template URL:

1. Open the link (or **Dashboard → Request → From template**).
2. Pre-filled with the seller's defaults.
3. Tweak quantity / customisations.
4. Publish — the original seller is automatically invited.

See [[Purchase Request Flow]] for the full state machine.

### 6.3 Managing your requests

**Dashboard → Request** shows all your requests with status:

| Status | Meaning |
|---|---|
| Draft | Saved, not yet published |
| Open | Live; sellers can offer |
| In negotiation | At least one offer received, conversation active |
| Accepted | You accepted an offer; awaiting payment |
| Funded | Payment in escrow; awaiting delivery |
| Shipped | Seller marked as shipped |
| Delivered | You confirmed receipt; escrow released |
| Completed | Closed; can leave a review |
| Disputed | A dispute is open |
| Cancelled | Cancelled before payment |
| Refunded | Money returned (dispute outcome) |
| Expired | Open too long with no acceptable offers |

Click a request to:

- See offers (compare prices, delivery times, seller ratings).
- Chat with a specific seller.
- Edit (only while in **Draft** or **Open**).
- Cancel (only while no payment is in flight).

---

## 7. Receiving and reviewing offers

When a seller submits an offer:

1. You get a **notification** (bell badge + email if enabled).
2. Click into the request → **Offers** tab.
3. Compare offers side-by-side:
   - Price
   - Delivery time
   - Seller rating + completed orders
   - Optional notes (use of materials, brand, etc.)

### 7.1 Negotiate

Each offer has a **Chat** button. Use it to:

- Ask clarifying questions.
- Request a counter-offer (lower price, faster delivery).
- Discuss customisations.

The seller can issue a **counter-offer** which appears as a new offer entry on the same chat. See [[Negotiation Flow]].

### 7.2 Accept

Click **Accept this offer** → confirmation modal → **Confirm**.

Effects:
- All other open offers on this request are auto-rejected.
- The request status moves to **Accepted**.
- The chat continues with this seller only.
- You are prompted to pay.

---

## 8. Paying for an order

Two payment paths. Pick at the **Pay** step.

### 8.1 Path A — SHKeeper invoice (recommended for non-crypto-native users)

1. Click **Pay with crypto invoice**.
2. Choose a token + network (e.g., USDT on BSC).
3. A QR code + address appears.
4. Open your wallet (any wallet that supports the network).
5. Scan the QR, send the exact amount, confirm in your wallet.
6. The page updates in real-time as the blockchain confirms (typically 30s–5 min).
7. Status moves to **Funded** when fully confirmed.

> [!warning]
> Send the **exact** amount on the **exact** network. Sending USDT on the wrong network (e.g., ERC-20 instead of BSC) WILL lose your funds. The displayed network is binding.

See [[Payment Flow - SHKeeper]].

### 8.2 Path B — Direct Web3 wallet

1. Click **Pay from connected wallet** (requires a connected wallet — see §3).
2. Your wallet pops up a transaction approval (token transfer to escrow address).
3. Approve & sign.
4. Wait for on-chain confirmation.
5. Backend verifies the transaction and moves status to **Funded**.

See [[Payment Flow - DePay & Web3]].

---

## 9. Tracking the order

Once **Funded**, the seller is notified to ship.

1. Seller marks the order **Shipped** — you receive a notification + optional tracking number.
2. When you receive the item, return to the request page → **Confirm receipt**.
3. This releases the escrow to the seller and moves status to **Delivered**.

See [[Delivery Confirmation Flow]].

> [!warning]
> Only confirm after you've received and inspected the item. Confirming is **irreversible** — to reverse, you must open a dispute.

---

## 10. Opening a dispute

If something is wrong (item not as described, never arrived, wrong quantity…):

1. On the request page → **Open dispute**.
2. Choose a reason (Not received / Damaged / Not as described / Other).
3. Upload evidence (photos, screenshots — max 5 MB each).
4. Write a clear narrative.
5. Submit.

An **admin mediator** is assigned within 24 hours. You and the seller will both be able to chat with the mediator and submit additional evidence.

Possible outcomes:

- **Full refund** — escrow returns to you.
- **Partial refund** — split between you and seller.
- **Release to seller** — your dispute is denied; escrow goes to seller.
- **Mutual cancellation** — both parties agree to refund.

See [[Dispute Flow]].

---

## 11. Rating

After the order is **Completed** (delivered or dispute resolved):

1. You're prompted to leave a rating + review.
2. Stars 1–5, plus a free-text comment (optional but encouraged).
3. The seller also rates you.

Ratings affect seller reputation (visible on their shop page). See [[Rating Flow]].

---

## 12. Earning & spending points

Points are earned via:

- Sign-up bonus
- Each completed purchase (X points per $1 — see [[LevelConfig]] for tiers)
- Referrals (you and the referred friend both get points)
- Special bonuses (admin-awarded for promotions)

**Dashboard → Points** shows:

- **Balance** — current points
- **Transactions** — history
- **Levels** — current tier + benefits + next-tier threshold
- **Referrals** — your unique referral link + invited friends

Higher levels unlock:

- Discount % on platform fee
- Priority support
- Free shipping (on partnered sellers)
- Special offers / early access

Spend points by selecting "Use points" at checkout (subject to seller acceptance).

See [[Referral Flow]] and the [[PointTransaction]] model.

---

## 13. Settings

### 13.1 Theme & display

Click the **cog** icon in the topbar to open the **Settings drawer**:

- Light / Dark / System mode
- Color preset
- Layout (Vertical / Mini / Horizontal)
- Direction (auto from language, override possible)
- Font family
- Border radius

See [[Settings & Theming]].

### 13.2 Language

Click the **flag chip** in the topbar to switch language. Persian and Arabic automatically flip the UI to RTL. See [[Internationalization & RTL]].

### 13.3 Notifications

**Dashboard → Account → Notifications**:

- Email notifications (on/off per category)
- In-app notifications (cannot be fully disabled)
- Push notifications (browser permission required)

### 13.4 Security

**Dashboard → Account → Security**:

- Change password
- Manage passkeys
- View active sessions / sign out elsewhere
- Two-factor authentication (if enabled)

---

## 14. Common issues

### "I can't sign in"

1. Confirm you're using the correct email.
2. Click **Forgot password** to reset.
3. If multiple failed attempts, the account is **temporarily locked** for cooldown.
4. If issue persists, contact support — see [[Support Guide]].

### "My email verification didn't arrive"

1. Check spam folder.
2. Click **Resend code** on the verify page.
3. Try a different email if the issue persists.

### "I sent USDT on the wrong network"

> [!warning]
> If you sent the wrong token/network combination, funds are likely **unrecoverable**. Contact support immediately with the transaction hash — recovery may be possible if the receive address is shared across networks.

### "The page froze / I see stale data"

1. Refresh the page.
2. If issue persists, paste the following in browser DevTools console (it clears stuck localStorage state):
   ```js
   // From frontend/cleanup-localstorage.js
   Object.keys(localStorage).filter(k => /^(manual-payment|buyer-step|LAST_(PAYMENT|TEMPLATE|SOCKET))-/.test(k)).forEach(k => localStorage.removeItem(k));
   ```
3. Refresh.

### "I can't pay — wallet won't connect"

1. Make sure your wallet extension is installed and unlocked.
2. Confirm you're on a **supported network** (BSC, Polygon, Ethereum, Sepolia).
3. Try WalletConnect (QR code) on mobile.

### "I want to delete my account"

Contact support — account deletion is a manual operation by admins to ensure all funds and disputes are cleared first.

---

## 15. Tips & best practices

> [!tip]
> - Save offers as drafts and revisit before publishing — it's harder to edit live requests.
> - Read seller ratings AND read recent reviews (not just the score).
> - Use chat early to clarify expectations — fewer disputes later.
> - Confirm receipt only after physical inspection.
> - Take photos at unboxing for evidence in case of dispute.
> - Keep your wallet seed phrase offline.

---

## 16. Related

- [[Seller Guide]] · [[Admin Guide]] · [[Support Guide]]
- Flows: [[Authentication Flow]] · [[Registration Flow]] · [[Purchase Request Flow]] · [[Payment Flow - SHKeeper]] · [[Payment Flow - DePay & Web3]] · [[Delivery Confirmation Flow]] · [[Dispute Flow]] · [[Rating Flow]] · [[Referral Flow]]
- Models: [[User]] · [[PurchaseRequest]] · [[Payment]] · [[Address]]
- [[Glossary]]