# MapleMarkets Autonomous Agent Interface Report
> Technical specification and integration manual for autonomous agents, LLM tool executors, and programmatic trading bots.
> Published: 2026-09-11 | Document Version: 2.4.0-SPEC | Protocol: REST / JSON / MCP

## 1. Executive Overview
MapleMarkets provides machine-readable discovery surfaces, standard REST endpoints, and Model Context Protocol (MCP) tool bindings to enable autonomous AI agents to query live spot pricing, inspect order book depth, verify transaction states, and monitor 2-of-3 multisig escrow contracts for the 2005 MMORPG economy.

- Canonical Host: `https://maplemarketssite.vercel.app`
- Primary Currency Symbol: Meso (M)
- Base Fiat / Settlement Units: USD, USDT (TRC-20 / ERC-20), SOL, USDC, BTC

## 2. Authentication & Agent Headers
Public market telemetry, spot rates, and transaction verification endpoints require no API keys. Programmatic agents should transmit identification headers:

```http
User-Agent: AgentName/1.0 (+https://yourdomain.com/agent-card)
Accept: application/json
X-Idempotency-Key: <UUID-v4>
```

When transmitting state-mutating requests (such as creating an escrow quote), always include an `X-Idempotency-Key` header to prevent duplicate orders during network retries.

## 3. Rate Limits & Throttling Parameters
All endpoints enforce standard token-bucket rate limits evaluated per IP address:

| Endpoint Category | Rate Limit | Burst Allowance | Penalty / Action |
| :--- | :--- | :--- | :--- |
| Public Telemetry & Health (`/api/health`) | 120 req / min | 200 requests | HTTP 429 (`Retry-After: 60`) |
| Market Spot Quotes (`/api/quotes/*`) | 60 req / min | 100 requests | HTTP 429 (`Retry-After: 60`) |
| Escrow & Order Status (`/api/crypto/verify*`) | 30 req / min | 50 requests | HTTP 429 (`Retry-After: 120`) |
| Conversational Chat Agent (`/api/chat`) | 15 req / min | 25 requests | HTTP 429 (`Retry-After: 180`) |

When rate-limited, the server returns an HTTP 429 status code with a standard `Retry-After: <seconds>` header. Agents MUST respect exponential backoff with jitter (`backoff = min(max_backoff, base * 2^attempt) + jitter`).

## 4. Core API Endpoints & JSON Contracts

### 4.1 System Health & Network Telemetry
`GET /api/health`
Returns system status, active server time, and node operational metrics.

**Response (200 OK):**
```json
{
  "status": "healthy",
  "version": "2.4.0",
  "timestamp": "2026-09-11T16:54:07Z",
  "services": {
    "pricing_engine": "online",
    "courier_dispatch": "online",
    "multisig_escrow": "online",
    "blockchain_indexers": {
      "solana": "synced",
      "tron": "synced",
      "bitcoin": "synced"
    }
  },
  "latency_ms": 14
}
```

### 4.2 Proof-of-Transaction Verification
`GET /api/crypto/verify-transaction?txId={hash}`
`GET /api/crypto/verify/{orderIdentifier}`
Validates on-chain cryptocurrency settlement and checks Proof-of-Transaction (PoTx) SHA-256 hash.

**Response (200 OK):**
```json
{
  "order_id": "MM-2026-8942",
  "status": "completed",
  "world": "fresh_launch",
  "meso_amount": 100000000,
  "in_game_tax_covered": 5263158,
  "gross_mesos_delivered": 105263158,
  "courier_character": "AgedMerchant74",
  "courier_level": 74,
  "bilateral_barter_item": "1x Snail Shell",
  "blockchain": "SOLANA",
  "tx_hash": "4kZ...9aQ",
  "potx_sha256": "8f4b2c1e7a9b0c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "timestamp": "2026-09-11T15:22:19Z"
}
```

### 4.3 Cody AI Concierge Conversation
`POST /api/chat`
Conversational chat interface for intelligent order assistance, dispatch guidance, and rule lookups.

**Request Payload:**
```json
{
  "messages": [
    {
      "role": "user",
      "content": "How do you avoid ban flags when delivering 50M mesos on the Fresh Launch server?"
    }
  ]
}
```

**Response (200 OK):**
```json
{
  "role": "assistant",
  "content": "MapleMarkets executes deliveries via peer-to-peer safety standards: 1) Established couriers with organic gameplay logs; 2) Reciprocal barter exchanging common in-game items to avoid empty one-way transfers; 3) Free Market Channel 1 room rotation; 4) Rate velocity limits. Real-money trading carries publisher ToS violation risks; MapleMarkets provides non-custodial escrow protection without promising ban immunity.",
  "canonical_url": "https://maplemarketssite.vercel.app/anti-ban-protocol"
}
```

### 4.4 Meso Spot Rates (Agent Tool: `get_meso_rates`)
`POST /api/quotes/meso-rates` (or via MCP Tool)
Calculates current spot rates and dynamic tax absorption overhead.

**Request Payload:**
```json
{
  "world": "fresh_launch",
  "volume_mesos": 100000000,
  "quote_currency": "USDT"
}
```

**Response (200 OK):**
```json
{
  "world": "fresh_launch",
  "net_volume_mesos": 100000000,
  "in_game_tax_rate": 0.05,
  "gross_mesos_to_deposit": 105263158,
  "spot_rate_usd_per_10m": 4.50,
  "total_price_usd": 45.00,
  "quote_currency": "USDT",
  "estimated_delivery_minutes": 5,
  "speed_sla_minutes": 15,
  "guarantee": "100% refund after 30 minutes if unfulfilled"
}
```

### 4.5 Order Book Depth (Agent Tool: `get_order_book`)
`GET /api/order-book?world=fresh_launch&limit=5`

**Response (200 OK):**
```json
{
  "world": "fresh_launch",
  "timestamp": "2026-09-11T16:50:00Z",
  "bids": [
    { "price_usd_per_10m": 4.10, "volume_mesos": 350000000, "bonded_sellers": 3 },
    { "price_usd_per_10m": 4.00, "volume_mesos": 800000000, "bonded_sellers": 6 }
  ],
  "asks": [
    { "price_usd_per_10m": 4.50, "volume_mesos": 500000000, "bonded_couriers": 4 },
    { "price_usd_per_10m": 4.65, "volume_mesos": 1200000000, "bonded_couriers": 8 }
  ],
  "spread_pct": 8.89,
  "reserve_liquidity_mesos": 2850000000
}
```

### 4.6 Escrow Status Check (Agent Tool: `check_escrow_status`)
`GET /api/escrow/status?order_id=MM-2026-8942`

**Response (200 OK):**
```json
{
  "order_id": "MM-2026-8942",
  "escrow_type": "2_of_3_multisig",
  "state": "RELEASED",
  "buyer_signed": true,
  "arbiter_signed": true,
  "dispute_open": false,
  "funds_released_at": "2026-09-11T15:22:19Z"
}
```

## 5. Mathematical Formulations & Fee Calculations

### 5.1 In-Game Free Market Trade Tax Absorption
MapleStory deducts an automatic system tax on direct trades inside the Free Market.
- For trades $\ge 10,000,000$ mesos: $T = 0.05$ (5.0%).
- For trades $5,000,000$ to $9,999,999$ mesos: $T = 0.04$ (4.0%).
- For trades $1,000,000$ to $4,999,999$ mesos: $T = 0.03$ (3.0%).

MapleMarkets algorithmically computes the required gross delivery deposit:
$$M_{\text{gross}} = \frac{M_{\text{net}}}{1 - T}$$

Example: To deliver $M_{\text{net}} = 100,000,000$ mesos ($T = 0.05$):
$$M_{\text{gross}} = \frac{100,000,000}{1 - 0.05} = \frac{100,000,000}{0.95} = 105,263,158\text{ mesos}$$
The game engine absorbs $5,263,158$ mesos and credits the client with exactly $100,000,000$ net mesos.

### 5.2 P2P Freelance Escrow Fee
For player freelance contracts (KPQ carries, equipment scrolling, quest assists), MapleMarkets deducts a transparent flat 12% take-rate from gross escrow funds upon buyer confirmation:
$$P_{\text{seller}} = C_{\text{gross}} \times (1 - 0.12) = C_{\text{gross}} \times 0.88$$

No deductions or hidden charges are made to the buyer.

## 6. RFC 7807 Error Contract
All agent errors return standard RFC 7807 Problem Details:

```json
{
  "type": "https://maplemarketssite.vercel.app/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Token bucket depleted.",
  "instance": "/api/quotes/meso-rates",
  "retry_after_seconds": 60
}
```

## 7. Model Context Protocol (MCP) Manifest
Autonomous agents running within MCP-enabled runtimes can inspect the formal tool schema at:
`https://maplemarketssite.vercel.app/.well-known/mcp.json`
Exposing:
- `get_meso_rates`
- `get_order_book`
- `check_escrow_status`