81625d35d2
- Add AML scope note to Handoff - RN Multichain Probe (sanctions-only vs full KYT) - Add human-blocked section with 3 precise next steps for owner - Create Task 11 Pre-flight Inventory: library choice, dev/prod flow, admin UI gaps, backend gaps, risks, acceptance criteria
401 lines
12 KiB
Markdown
401 lines
12 KiB
Markdown
---
|
||
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]]
|