---
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 from your own wallet:

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 required for the in-house Request Network checkout. See [[Escrow Flow]] and [[Request Network Integration Constraints]].

---

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

The current payment path is the Request Network in-house checkout.

### 8.1 Request Network checkout

1. Click **Pay**.
2. Choose a token + network (e.g., USDT on BSC).
3. Connect or select your wallet.
4. Approve the token spend if prompted.
5. Confirm the payment transaction 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 [[Escrow Flow]].

---

## 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]] · [[Escrow Flow]] · [[Delivery Confirmation Flow]] · [[Dispute Flow]] · [[Rating Flow]] · [[Referral Flow]]
- Models: [[User]] · [[PurchaseRequest]] · [[Payment]] · [[Address]]
- [[Glossary]]
