> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.pgecom.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 04 - Trading Step by Step

# Trading Step by Step

This guide covers the complete trade lifecycle — from placing a trade to completion, including timers, cancellation, payment timeouts, and everything in between.

---

## Understanding the Trade Lifecycle

Every trade goes through a series of states in a **simplified auto-acceptance flow**:

```
Payment Pending → Payment Confirmed → Completed
       ↓                ↓                ↓
  Cancelled        Cancelled        Disputed → Dispute Resolved
       ↓
  Auto-Expired (if payment timeout)
```

| State | What Is Happening |
|-------|-------------------|
| **Payment Pending** | Trade auto-accepted and funds locked. Buyer must send payment before timer expires. |
| **Payment Confirmed** | Buyer has marked payment as sent and uploaded proof. Seller must verify before timer expires. |
| **Completed** | Seller confirmed payment received. Trade is done. Crypto released from escrow. |
| **Cancelled** | One party cancelled the trade. Fees apply. |
| **Disputed** | A dispute has been opened claiming an issue with the trade. |
| **Auto-Expired** | Payment timer ran out. Progressive penalty applied (fees + ban). |

**Key Change**: Trades are **automatically accepted** when placed. There is no longer a "Pending" state waiting for seller acceptance. Funds are immediately locked in escrow and the payment timer starts.

The trade detail page shows a **visual progress tracker** at the top so you always know where the trade stands.

---

## Finding Your Trades

1. Go to **Dashboard > Trades**.
2. You see a list of all trades you are involved in (as buyer or seller).
3. Use the **search bar** to find trades by ID, asset, currency, or status.
4. Toggle the **filter panel** to narrow results by:
   - **Status** — Active, Completed, Cancelled, Disputed
   - **Trade Type** — Buy or Sell
   - **Payment Method** — Filter by specific method
5. Active filters appear as **dismissible badges** above the results.
6. A results count shows "Showing X of Y trades".
7. Click any trade row to open its detail page.

---

## Trading as a Buyer

### Step 1 — Place a Trade

1. Go to **Marketplace**.
2. Find a **Sell** offer that matches what you want to buy.
3. Click **Buy** on the offer card.
4. Complete the [2-step Place Trade dialog](./02-marketplace.md#placing-a-trade):
   - Enter your amount (within min/max limits)
   - Select a payment method
   - Review fees and terms
   - Confirm the trade
5. **Trade is auto-accepted immediately** and you are redirected to the trade detail page.

> **Important**: You must have a **verified email address** to place trades. See [Settings & Profile guide](./10-settings-profile.md) for email verification.

### Step 2 — Send Payment (Payment Pending)

**No waiting for acceptance!** The trade starts in **Payment Pending** status immediately:

1. The seller's **payment details** appear on the trade page under "Seller Payment Information".
2. Payment details vary by method:
   - **Bank Transfer** — Bank name, account number, account holder name
   - **Mobile Money** (MonCash, NatCash, M-Pesa, etc.) — Phone number, account holder name
   - **Digital Wallet** (PayPal, Venmo, etc.) — Email or username
   - **Cash** — Meeting location, contact information
3. **Payment timer** starts counting down (typically 15 minutes, set by offer creator).
4. Send the payment **outside the platform** using the provided details.
5. You must complete payment before the timer expires or face **progressive penalties** (see [Payment Timeouts](#payment-timeouts) below).

> **Timer Warning Colors**:
> - **Blue** — Plenty of time remaining
> - **Orange** — Less than 5 minutes left — urgent
> - **Red** — Timer has expired

### Step 3 — Upload Payment Proof

1. On the trade detail page, click **Mark Payment as Sent**.
2. Choose how to provide proof:
   - **Upload Image** — Drag and drop or click to upload a screenshot of your payment receipt (JPEG, PNG, WebP, GIF — max 10MB). Images are automatically optimized.
   - **Enter URL** — Paste a link to your receipt image or enter a transaction reference ID.
3. Optionally add notes about the payment.
4. Click **Submit Payment Proof**.

The status changes to **Payment Confirmed** and the **release timer** starts for the seller.

### Step 4 — Wait for Confirmation

The seller verifies that your payment was received. Once they confirm, the trade completes automatically. You will see a **confetti animation** and a success banner.

> **Tip**: Use the [trade chat](./08-trade-chat.md) to communicate with the seller if there are any questions about the payment.

---

## Trading as a Seller

### Step 1 — Receive a Trade

When someone places a trade on your offer:
- It appears immediately in **Dashboard > Trades** with **Payment Pending** status
- **Funds are auto-locked** in escrow
- **Payment timer** starts immediately
- You may receive an email notification (if enabled)

**No acceptance step needed** — the trade is ready for the buyer to pay.

### Step 2 — Wait for Payment

The buyer sees your saved payment details (configured when you created the offer) and sends payment. The **payment timer** counts down.

You can:
- **Extend the payment timer** if the buyer needs more time (see [Extending Timers](#extending-timers))
- **Cancel the trade** if needed (2% fee applies - see [Cancelling a Trade](#cancelling-a-trade))
- **Chat with the buyer** for updates

### Step 3 — Review Payment Proof

When the buyer marks payment as sent:
1. Status changes to **Payment Confirmed**
2. **Release timer** starts (typically 30 minutes, set when you created the offer)
3. Payment proof appears on the trade detail page
4. Click the image to view full size

### Step 4 — Verify and Confirm

1. **Check your bank/wallet/phone** to verify the payment was actually received.
2. Review the buyer's payment proof on the trade detail page.
3. If payment received, click **Confirm Payment Received**.
4. The trade completes with a **confetti animation**.
5. Crypto is released from escrow to the buyer.

> **Warning**: Only confirm payment after you have verified the funds are actually in your account. Once confirmed, the trade cannot be reversed.

> **Important**: You must confirm before the release timer expires or the buyer can open an appeal.

---

## Payment Timers

Trades have **two timers** that enforce deadlines to keep trades moving quickly and prevent time-wasters.

### Payment Timer

- **Starts**: Immediately when trade is placed (auto-accepted)
- **Who**: Buyer must send payment and upload proof before this expires
- **Default**: 15 minutes (configurable by offer creator: 15, 30, 60, or custom minutes)
- **Displayed**: Compact banner with countdown at top of trade page
- **What happens if expired**: See [Payment Timeouts](#payment-timeouts) below

### Release Timer

- **Starts**: When buyer marks payment as sent (status becomes Payment Confirmed)
- **Who**: Seller must confirm payment receipt before this expires
- **Default**: 30 minutes (configurable by offer creator: 15, 30, 60, or custom minutes)
- **Displayed**: Compact banner with countdown at top of trade page
- **What happens if expired**: Buyer can open a dispute/appeal

### Timer Colors

| Color | Meaning |
|-------|---------|
| **Blue** | More than 5 minutes remaining |
| **Orange** | Less than 5 minutes left — urgent action needed |
| **Red** | Timer has expired |

> **Auto-refresh**: Timers update every 15 seconds so both parties always see the current countdown.

---

## Extending Timers

Either party can extend the timer to give the other party more time, up to a **maximum of 7 days total** from trade creation.

### Payment Timer Extension (Seller Extends for Buyer)

The **seller** can extend the payment timer if the buyer needs more time to pay.

**Extension Options**:
- 15 minutes
- 30 minutes
- 1 hour (60 minutes)
- 1 day (24 hours / 1440 minutes)
- 3 days (72 hours / 4320 minutes)
- 5 days (120 hours / 7200 minutes)

**How to extend**:
1. Click the **"Extend Timer"** dropdown next to the payment timer banner
2. Select your desired extension time
3. Confirm the extension

**Limits**:
- Maximum total time from trade creation to deadline: **7 days**
- If adding the extension would exceed 7 days, you'll see an error with the maximum allowed extension
- Extensions are tracked (counter shows how many times extended)

### Release Timer Extension (Buyer Extends for Seller)

The **buyer** can extend the release timer if the seller needs more time to confirm payment.

- Same extension options and limits as payment timer
- Same 7-day maximum total time limit

### System Messages

When a timer is extended, both parties receive a **system message** in the trade chat showing:
- Who extended the timer
- How much time was added
- New deadline timestamp

---

## Payment Timeouts

If a **buyer** fails to send payment before the payment timer expires, the system automatically applies **progressive penalties** to discourage repeat offenders.

### What Happens

When the payment deadline is reached and payment hasn't been marked as sent:

1. **Trade is auto-cancelled** (status becomes "cancelled", `autoExpired: true`)
2. **Timeout fee is charged** (progressive based on offense count)
3. **50% of fee goes to seller** as compensation for their time
4. **Trading ban is applied** (progressive duration)
5. **Email notifications sent** to both parties

### Progressive Penalty System

Penalties increase with each timeout offense:

| Offense # | Fee Amount | Seller Gets | Platform Gets | Ban Duration |
|-----------|------------|-------------|---------------|--------------|
| **1st** | **$3.99 USD** | $1.995 USD | $1.995 USD | **24 hours** |
| **2nd** | **$7.99 USD** | $3.995 USD | $3.995 USD | **48 hours** |
| **3rd+** | **$15.99 USD** | $7.995 USD | $7.995 USD | **1 week (168 hours)** |

### How Fees Are Charged

**If buyer has sufficient USD balance**:
- Fee is deducted automatically from buyer's wallet
- Seller receives their 50% share immediately
- Transaction appears in both wallet histories

**If buyer has insufficient balance**:
- **Debt is created** for the full amount
- Buyer cannot place new trades until debt is paid
- No money is transferred to seller until debt is paid
- See [Wallet guide](./07-wallet.md) for paying debt

### Trading Bans

While banned, buyers **CANNOT**:
- ❌ Place new trades
- ❌ Accept trade offers
- ❌ Initiate any buy transactions

While banned, buyers **CAN**:
- ✅ View existing trades
- ✅ Complete ongoing trades (if any)
- ✅ Chat with trade partners
- ✅ Deposit funds to wallet
- ✅ Pay outstanding debts
- ✅ Submit appeals (with $4.99 fee)

Ban expiration is shown in error messages and dashboard alerts.

### Preventing Timeouts

**As a buyer**:
- Only place trades when you're ready to pay immediately
- Have payment method ready before clicking "Buy"
- If you need more time, ask the seller to extend the timer via chat
- Set calendar reminders for active trades

**As a seller**:
- Set reasonable payment time limits (15-30 minutes typical)
- Be available to extend timer if buyer has legitimate delays
- Monitor trades and communicate proactively

### Appeals

If a timeout occurred due to:
- ✅ Payment was made but not confirmed
- ✅ Technical issues prevented payment upload
- ✅ Seller provided wrong payment information
- ✅ Extenuating circumstances (emergency, etc.)

You can submit an **appeal** with a $4.99 fee (refunded if approved). See [Disputes & Appeals guide](./06-disputes-appeals.md) for the complete appeal process.

> **Learn More**: See [Payment Timeout System](../PAYMENT_TIMEOUT_SYSTEM.md) for complete documentation including analytics, debt tracking, and admin tools.

---

## Cancelling a Trade

Either party can cancel a trade during certain states, but **fees apply** to discourage abuse.

### When Can You Cancel?

- ✅ During **Payment Pending** — Both buyer and seller can cancel
- ✅ During **Payment Confirmed** — **Only buyer** can cancel (seller cannot, since buyer may have already sent money)
- ❌ **Not available** after completing, or if already disputed
- ❌ **Not available** after timer has expired — use an appeal instead

### Cancellation Fees

| Who Cancels | Fee | Details |
|-------------|-----|---------|
| **Buyer** | **$3.99 USD** | $1.995 goes to seller as compensation, $1.995 to platform |
| **Seller** | **2% of trade amount** | Deducted from the crypto being refunded |

**Buyer Example**:
- Trade amount: 0.5 BTC worth $15,000 USD
- Buyer cancels
- Buyer charged: $3.99 USD (flat fee)
- Seller receives: $1.995 USD (compensation)
- Platform receives: $1.995 USD

**Seller Example**:
- Trade amount: 0.5 BTC
- Seller cancels
- Cancellation fee: 0.01 BTC (2% of 0.5 BTC)
- Seller gets refund: 0.49 BTC (0.5 - 0.01 fee)
- Platform receives: 0.01 BTC

### How to Cancel

1. On the trade detail page, click **Cancel Trade** button.
2. Read the fee information displayed.
3. Enter a **cancellation reason** (required).
4. Click **Yes, Cancel Trade** to confirm.
5. Fee is charged and escrow funds are refunded (minus seller's fee if applicable).

### What Happens After Cancellation

1. **Trade status** changes to "Cancelled"
2. **Cancellation fee** is charged immediately
3. **Escrow funds** are unlocked and refunded (minus fee for seller)
4. **System message** posted to trade chat
5. **Email notification** sent to the other party
6. **Timeline event** added showing who cancelled and why

---

## Viewing Trade Details

The trade detail page organizes information into collapsible accordion sections:

### Trade Details
- Trade status and escrow status
- Asset being traded
- Amount and price per unit
- Currency and payment method
- Total trade value
- **Payment timer** (if in Payment Pending status)
- **Release timer** (if in Payment Confirmed status)

### Buyer / Seller Information
- Buyer name and email (with "You" badge if you are the buyer)
- Seller name and email (with "You" badge if you are the seller)
- **Block** / **Unblock** buttons for the other party

### Seller Payment Information
- The payment details the seller provided (rendered based on payment type)
- Field types vary: phone numbers, bank accounts, emails, physical locations
- Copy buttons for easy copying

### Payment Proof
- Image preview (clickable to view full size) if proof was uploaded
- Text reference if a URL or transaction ID was provided
- "Payment proof hasn't been submitted yet" if no proof exists

### Trade Timeline
- Complete event history with timestamps
- Every state change, action, and event is recorded
- Timer extensions, fee charges, and ban applications logged

### Trade Chat
- Real-time messaging with the other party
- See the [Trade Chat guide](./08-trade-chat.md) for full details

> **Tip**: Click the section headers to expand or collapse them.

---

## Email Verification Requirement

To protect the platform from abuse and ensure account security, you **must verify your email address** before you can:

- ❌ Place trades (buy from marketplace)
- ❌ Create trade offers (sell on marketplace)

### How to Verify Your Email

1. Go to **Dashboard > Settings > Security** tab
2. Click **Send Code** button
3. Check your email for a 6-digit verification code (expires in 10 minutes)
4. Enter the code in the verification field
5. Click **Verify**
6. Email verified ✅ — you can now trade!

**Email verification ensures**:
- Account ownership confirmation
- Ability to recover your account
- Receive important notifications (timeout alerts, trade updates, etc.)
- Required for enabling two-factor authentication (2FA)

See the [Settings & Profile guide](./10-settings-profile.md) for more details on email verification and security features.

---

## Viewer Mode

If you are a team **admin**, **owner**, or **viewer** monitoring a trade you are not directly part of, you see the trade in **read-only mode**:

- All action buttons are disabled
- Chat is read-only (you can see messages but not send)
- You can view all trade details but cannot take any actions
- Useful for customer support, compliance, and team oversight

---

## Quick Reference

### Trade States

| State | Buyer Action | Seller Action |
|-------|--------------|---------------|
| Payment Pending | Send payment & upload proof | Wait or extend timer |
| Payment Confirmed | Wait for seller confirmation | Verify payment & confirm |
| Completed | Rate seller (optional) | Rate buyer (optional) |
| Cancelled | N/A | N/A |
| Disputed | Provide evidence | Provide evidence |

### Action Buttons by Role

| Action | Buyer | Seller | When Available |
|--------|-------|--------|----------------|
| Mark Payment Sent | ✅ | ❌ | Payment Pending |
| Confirm Payment | ❌ | ✅ | Payment Confirmed |
| Extend Payment Timer | ❌ | ✅ | Payment Pending |
| Extend Release Timer | ✅ | ❌ | Payment Confirmed |
| Cancel Trade | ✅ | ✅ | Payment Pending or Payment Confirmed (buyer only) |
| Open Dispute | ✅ | ✅ | Payment Confirmed or after timer expiry |

---

## Related Guides

- [Marketplace Guide](./02-marketplace.md) — Finding and filtering offers
- [Creating Offers Guide](./03-creating-offers.md) — Setting up your sell offers
- [Payments Guide](./05-payments.md) — Payment methods and verification
- [Disputes & Appeals Guide](./06-disputes-appeals.md) — Handling problems and appeals
- [Wallet Guide](./07-wallet.md) — Managing funds and paying debts
- [Trade Chat Guide](./08-trade-chat.md) — Communicating with trade partners
- [Payment Timeout System](../PAYMENT_TIMEOUT_SYSTEM.md) — Complete progressive penalty documentation

---

**Last Updated**: February 2026
**Version**: 2.0.0 — Auto-Acceptance & Progressive Penalties
