# Escrow System

The KayakNet Escrow System provides trustless cryptocurrency transactions for the marketplace.

## How It Works

```
┌─────────┐         ┌─────────┐         ┌─────────┐
│  Buyer  │         │ Escrow  │         │ Seller  │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │  1. Create Order  │                   │
     │──────────────────▶│                   │
     │                   │                   │
     │  2. Pay to Escrow │                   │
     │──────────────────▶│                   │
     │                   │                   │
     │                   │  3. Notify Seller │
     │                   │──────────────────▶│
     │                   │                   │
     │                   │  4. Ship Item     │
     │                   │◀──────────────────│
     │                   │                   │
     │  5. Receive Item  │                   │
     │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─│                   │
     │                   │                   │
     │  6. Confirm       │                   │
     │──────────────────▶│                   │
     │                   │                   │
     │                   │  7. Release Funds │
     │                   │──────────────────▶│
     │                   │                   │
```

## Supported Cryptocurrencies

| Currency | Symbol | Privacy Level             |
| -------- | ------ | ------------------------- |
| Monero   | XMR    | Maximum (default private) |
| Zcash    | ZEC    | High (shielded addresses) |

### Why These Currencies?

* **Bitcoin** - Not supported (transparent blockchain)
* **Monero** - Ring signatures, stealth addresses
* **Zcash** - Zero-knowledge proofs

## Order States

| State       | Description                       | Duration       |
| ----------- | --------------------------------- | -------------- |
| `created`   | Order initiated, awaiting payment | 24 hours       |
| `funded`    | Payment received, held in escrow  | Until shipped  |
| `shipped`   | Seller marked as shipped          | 14 days        |
| `completed` | Buyer confirmed receipt           | Final          |
| `disputed`  | Dispute opened                    | Until resolved |
| `refunded`  | Funds returned to buyer           | Final          |
| `expired`   | Order timed out                   | Final          |

## Creating an Escrow

### For Buyers

1. **Click "BUY"** on a listing
2. **Select currency** (XMR or ZEC)
3. **Enter delivery info** (encrypted)
4. **Review order details**
5. **Click "CREATE ORDER"**

You'll receive:

* **Escrow Address** - Where to send payment
* **Amount** - Exact crypto amount
* **Expiry** - Time limit for payment

### Payment

Send the **exact** amount to the escrow address:

```
Amount: 0.00123456 XMR
Address: 44zFk33yjuwLLWSkj1i2JMiiNX9HifKinA8v...
Fee: 2.5% (included)
Expires: 24 hours
```

**Important:**

* Send the EXACT amount shown
* Include enough for network fees
* Use correct currency network

### Confirmation

After payment:

1. Transaction broadcasts to network
2. KayakNet monitors for confirmations
3. Required confirmations: 10 (XMR), 6 (ZEC)
4. State changes to "funded"
5. Seller notified automatically

## For Sellers

### When Order is Funded

1. Check **SALES** tab in marketplace
2. Order shows "FUNDED" state
3. Delivery info is decrypted

### Fulfilling Order

1. Ship the item
2. Click **"MARK AS SHIPPED"**
3. Enter tracking info (optional)
4. State changes to "shipped"

### Receiving Payment

* Buyer confirms → Funds released instantly
* 14 days pass → Funds auto-release
* Dispute → Wait for resolution

## Disputes

### Opening a Dispute

As a buyer, if something's wrong:

1. Go to order details
2. Click **"OPEN DISPUTE"**
3. Select reason:
   * Item not received
   * Item not as described
   * Wrong item
   * Damaged item
   * Other
4. Describe the issue
5. Upload evidence (photos, screenshots)

### Dispute Resolution

1. **Seller Response** - 48 hours to respond
2. **Evidence Review** - Both parties submit proof
3. **Mediation** - Network mediators review
4. **Decision** - Funds released or refunded

### Auto-Resolution

If no response:

* Buyer dispute → Refunded after 7 days
* Seller dispute → Released after 7 days

## Fees

| Fee Type     | Amount   | When                |
| ------------ | -------- | ------------------- |
| Platform Fee | 2.5%     | On completion       |
| Network Fee  | Variable | On each transaction |
| Dispute Fee  | 1%       | If dispute filed    |

Platform fees fund network operations and development.

## Security

### Key Protection

* Escrow wallets on bootstrap node
* Multi-signature for large amounts (coming)
* Cold storage for reserves

### Address Generation

Each order gets a unique address:

```
Order: #1234
├── XMR subaddress: unique per order
└── ZEC z-address: unique per order
```

### No Custodial Risk

* Funds held minimum time
* Released immediately on confirmation
* No pooling of buyer funds

## Manual Confirmation

If automatic payment detection fails:

1. Go to order details
2. Click **"MANUAL CONFIRM"**
3. Enter transaction ID (TXID)
4. Submit

This is useful when:

* Wallet sync is behind
* Network congestion
* Unusual transaction

## API Reference

### Create Escrow

```
POST /api/escrow/create
{
  "listing_id": "abc123",
  "currency": "XMR",
  "buyer_address": "44zFk...",
  "delivery_info": "encrypted..."
}
```

### Check Status

```
GET /api/escrow/status?id=abc123
```

### Mark Shipped

```
POST /api/escrow/ship
{
  "escrow_id": "abc123",
  "tracking_info": "optional"
}
```

### Confirm Receipt

```
POST /api/escrow/release
{
  "escrow_id": "abc123"
}
```

## Best Practices

### For Buyers

* Verify seller reputation first
* Pay exact amount shown
* Check address carefully
* Confirm receipt promptly
* Keep transaction records

### For Sellers

* Ship promptly when funded
* Provide tracking when possible
* Communicate with buyers
* Keep shipping receipts
* Respond to disputes quickly

## Troubleshooting

### Payment Not Detected

1. Verify you sent correct amount
2. Check transaction confirmed
3. Use manual confirmation
4. Wait for wallet sync

### Funds Not Released

1. Check if buyer confirmed
2. Wait for auto-release (14 days)
3. Contact support if stuck

### Order Expired

* Payment wasn't received in time
* Create new order
* Use faster confirmation next time


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kayaknet.io/features/escrow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.