# Trust Me Bro — Full API Documentation

> Agent discovery platform for Dubai — like Google for AI agents.
> Base URL: https://tmb-dubai.com

## Overview

Trust Me Bro is an agent discovery platform. AI agents are listed here so users, LLMs, and other agents can find and use them. The first listed agent is Pearl Hunter (Kashf كشف), an autonomous price arbitrage agent for UAE consumer electronics.

## Architecture

- **Frontend**: Single-page app at /agent/pearl-hunter
- **Backend**: Python/Flask REST API
- **Data**: Real-time price scraping from 5 UAE stores
- **Payments**: Stripe (3% platform fee on group buys)
- **Agent Protocol**: AMMC via FindAppKeys (ceremonial reporting layer)
- **Auth**: Replit Auth (required only for write operations)

---

## API Reference

### 1. Search Products

**GET /api/search?q={query}**

Search for electronics products across all 5 UAE stores. Returns results ranked by relevance with prices, trust scores, and savings calculations.

Query Parameters:
- q (string, required): Product search query

Response:
```json
{
  "results": [
    {
      "id": 42,
      "name": "iPhone 16 Pro 256GB",
      "price": 4299.00,
      "original_price": 4699.00,
      "currency": "AED",
      "store": "Amazon.ae",
      "url": "https://amazon.ae/...",
      "image_url": "https://...",
      "trust_score": 92,
      "savings_percent": 8.5,
      "in_stock": true
    }
  ],
  "query": "iPhone 16 Pro",
  "count": 15,
  "stores_searched": 5
}
```

Example: GET /api/search?q=iPhone+16+Pro

---

### 2. Get Deals

**GET /api/deals?limit={n}**

Returns current arbitrage deals — products with significant price drops or cross-store price differences.

Query Parameters:
- limit (integer, optional, default=40): Maximum results

Response:
```json
{
  "deals": [
    {
      "product_name": "Samsung Galaxy S25 Ultra",
      "current_price": 3899.00,
      "original_price": 4499.00,
      "store": "Noon",
      "savings_percent": 13.3,
      "url": "https://noon.com/...",
      "detected_at": "2025-01-15T10:30:00Z"
    }
  ]
}
```

---

### 3. Autocomplete

**GET /api/autocomplete?q={query}**

Returns search suggestions based on partial query input.

Query Parameters:
- q (string, required): Partial search query (minimum 2 characters)

Response:
```json
{
  "suggestions": [
    "iPhone 16 Pro",
    "iPhone 16 Pro Max",
    "iPhone 15"
  ]
}
```

---

### 4. Group Buy Sessions

**GET /api/ammc/sessions**

Lists active group buy sessions. These are coordinated bulk purchases where users join together.

Response:
```json
{
  "sessions": [
    {
      "id": 1,
      "product_name": "iPhone 16 Pro 256GB",
      "target_price_aed": 3999.00,
      "current_best_price_aed": 4299.00,
      "participant_count": 5,
      "target_count": 10,
      "status": "open",
      "deadline": "2025-01-20T23:59:59Z",
      "savings_percent": 15.2
    }
  ]
}
```

Statuses: open, funding, funded, purchasing, completed, expired

---

### 5. Session Detail

**GET /api/ammc/sessions/{session_id}**

Get detailed information for a specific group buy session including participant status.

Path Parameters:
- session_id (integer, required): Session ID

---

### 6. Verify Seller

**GET /api/seller/{seller_name}/verify**

Verify a seller's trustworthiness. Checks DED (Dubai Economy and Tourism) license, customer ratings, and transaction history.

Path Parameters:
- seller_name (string, required): Seller name (e.g., "Amazon.ae", "Noon")

Response:
```json
{
  "seller": "Amazon.ae",
  "trust_score": 95,
  "ded_verified": true,
  "ded_license": "DED-12345",
  "rating": 4.7,
  "total_reviews": 15000,
  "verified_at": "2025-01-15T10:00:00Z"
}
```

---

### 7. Price Prediction

**GET /api/predict/{product_id}**

Get AI-powered price drop predictions for a specific product based on historical price data.

Path Parameters:
- product_id (integer, required): Product ID from search results

Response:
```json
{
  "product_id": 42,
  "product_name": "iPhone 16 Pro 256GB",
  "current_price": 4299.00,
  "prediction": {
    "drop_probability": 0.72,
    "estimated_drop_percent": 8,
    "estimated_new_price": 3955.00,
    "timeframe_days": 14,
    "recommended_action": "Wait — 72% chance of price drop within 2 weeks",
    "confidence": "medium"
  }
}
```

---

### 8. Agent Activity Log

**GET /api/agent/activity**

Returns recent Pearl Hunter agent activities — what it's been doing autonomously.

Response:
```json
{
  "activities": [
    {
      "timestamp": "2025-01-15T10:30:00Z",
      "action": "price_scan",
      "detail": "Scanned 5 stores for iPhone 16 Pro",
      "result": "Found 15% price difference between Amazon.ae and Noon"
    }
  ]
}
```

---

### 9. AppKeys Network Status

**GET /api/appkeys/status**

Returns status of the AppKeys AMMC network connection and agent reputation.

---

## Authenticated Endpoints (Require Replit Auth)

### Join Group Buy
**POST /api/ammc/join**
Body: {"product_id": 42}

### Checkout Group Buy
**POST /api/ammc/{session_id}/checkout**
Creates a Stripe checkout session.

### Create Price Alert
**POST /api/alerts**
Body: {"product_id": 42, "target_price": 3999.00}

### List My Alerts
**GET /api/alerts**

### Delete Alert
**DELETE /api/alerts/{alert_id}**

---

## Stores Monitored

| Store | Type | URL |
|---|---|---|
| Amazon.ae | Marketplace | https://amazon.ae |
| Noon | Marketplace | https://noon.com |
| Sharaf DG | Electronics Retailer | https://sharafdg.com |
| Dubizzle | Classifieds | https://dubizzle.com |
| Carrefour UAE | Hypermarket | https://carrefouruae.com |

## Currency

All prices are in AED (United Arab Emirates Dirham). 1 USD is approximately 3.67 AED.

## Rate Limits

No rate limits are currently enforced on public endpoints. Please be respectful with request frequency.

## Discovery Endpoints

| File | URL | Purpose |
|---|---|---|
| llms.txt | /llms.txt | Quick LLM-readable summary |
| llms-full.txt | /llms-full.txt | This file — full API docs |
| agent.md | /agent.md | Agent profile in Markdown |
| OpenAPI | /openapi.json | Machine-readable API spec |
| AI Plugin | /.well-known/ai-plugin.json | ChatGPT/OpenAI plugin manifest |
| MCP | /.well-known/mcp.json | WebMCP server manifest |
| Agent Card | /.well-known/agent.json | Agent discovery metadata |
| Security | /.well-known/security.txt | Security contact |
| Robots | /robots.txt | Crawler directives |
| Sitemap | /sitemap.xml | URL index |