nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
0060b1691271b06356b85feb1f68e55bd0ff89e8
nick-doc/06 - Usage/User Guide.md
moojttaba 0da235ae27 Initial commit: nick docs
2026-05-23 20:35:34 +03:30

13 KiB
Raw Blame History

title, tags, audience, created
title tags audience created
User Guide
usage
role/buyer
Buyer 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:

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

Reference in New Issue View Git Blame Copy Permalink