Files

Siavash Sameni 81625d35d2 docs: AML scope note, human-blocked items, Task #11 pre-flight inventory

- 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

2026-05-28 20:42:42 +04:00

12 KiB

Raw Blame History

title, tags, audience, created

title

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

Visit /auth/jwt/sign-up.
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.)
Optional: enter a referral code if a friend invited you (you'll both earn points — see Referral Flow).
Accept Terms of Service.
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

Open the verification email and copy the 6-digit code.
Paste into the Verify page (/auth/jwt/verify).
Click Verify.
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.

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

3. Connecting a wallet

If you want to pay from your own wallet:

Dashboard → Account → Wallet.
Click Connect Wallet.
Choose MetaMask (browser) or WalletConnect (mobile).
Approve the connection request in your wallet.
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)

Dashboard → Account → Passkey.
Click Add passkey.
Follow your device's prompt (Touch ID, Face ID, Windows Hello, USB key…).
Name the passkey ("MacBook", "iPhone 15", …) and save.
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

Dashboard → Request → + New Request.
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).
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:

Open the link (or Dashboard → Request → From template).
Pre-filled with the seller's defaults.
Tweak quantity / customisations.
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:

You get a notification (bell badge + email if enabled).
Click into the request → Offers tab.
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

Click Pay.
Choose a token + network (e.g., USDT on BSC).
Connect or select your wallet.
Approve the token spend if prompted.
Confirm the payment transaction in your wallet.
The page updates in real-time as the blockchain confirms (typically 30s–5 min).
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.

Seller marks the order Shipped — you receive a notification + optional tracking number.
When you receive the item, return to the request page → Confirm receipt.
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…):

On the request page → Open dispute.
Choose a reason (Not received / Damaged / Not as described / Other).
Upload evidence (photos, screenshots — max 5 MB each).
Write a clear narrative.
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):

You're prompted to leave a rating + review.
Stars 1–5, plus a free-text comment (optional but encouraged).
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

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

"My email verification didn't arrive"

Check spam folder.
Click Resend code on the verify page.
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"

Refresh the page.

If issue persists, paste the following in browser DevTools console (it clears stuck localStorage state):

// 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));

Refresh.

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

Make sure your wallet extension is installed and unlocked.
Confirm you're on a supported network (BSC, Polygon, Ethereum, Sepolia).
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.

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

12 KiB Raw Blame History Unescape Escape