# ShippingRates API - Full Documentation for LLMs

> ShippingRates is the world's first x402-native shipping data API. AI agents can query container shipping rates, demurrage & detention charges, local charges, inland haulage, and CFS tariffs — paying per-request with USDC on Base or Solana. No API keys. No accounts. No subscriptions.

## API Base URL
https://api.shippingrates.org

## MCP Server
https://mcp.shippingrates.org

## Payment Protocol
x402 (HTTP 402 Payment Required)
- Supported Networks: Base (EVM), Solana
- Currency: USDC
- Facilitator: https://facilitator.payai.network
- Settlement: Instant (~200ms)

## Authentication
None required. Payment is authentication. Send a request, receive a 402 response with payment terms, sign payment, retry with proof header.

## Pricing (per request)
| Endpoint | Price | Description |
|----------|-------|-------------|
| /api/dd/calculate | $0.10 | Calculate D&D charges for a container |
| /api/dd/compare | $0.25 | Compare D&D across shipping lines |
| /api/local-charges | $0.05 | Port local charges lookup |
| /api/inland/search | $0.03 | Search inland transport routes |
| /api/cfs | $0.05 | Container freight station tariffs |
| /api/inland | $0.05 | Inland haulage rates |

## Free Endpoints (no payment required)
| Endpoint | Description |
|----------|-------------|
| /api/lines | List available shipping lines |
| /api/stats | Database statistics |
| /health | Server health and version |

---

## Endpoint Details

### 1. GET /api/dd/calculate
Calculate demurrage and detention charges for a specific container at a port.

**Price:** $0.10 per request

**Query Parameters:**
- `line` (required) — Shipping line code (e.g., "MSC", "MAERSK", "COSCO", "HAPAG", "ONE", "EVERGREEN")
- `port` (required) — Port code or name (e.g., "INMUN" for Mumbai, "INNSA" for Nhava Sheva)
- `container_type` (optional) — Container size, default "20GP" (options: "20GP", "40GP", "40HC")
- `days` (optional) — Number of days to calculate, default 14

**Example Request:**
```
GET https://api.shippingrates.org/api/dd/calculate?line=MSC&port=INMUN&container_type=20GP&days=14
```

**Example Response:**
```json
{
  "line": "MSC",
  "port": "INMUN",
  "container_type": "20GP",
  "free_days": {
    "demurrage": 7,
    "detention": 7
  },
  "charges": {
    "demurrage": [
      {"day_range": "8-14", "rate_per_day": 75, "currency": "USD"},
      {"day_range": "15-21", "rate_per_day": 150, "currency": "USD"}
    ],
    "detention": [
      {"day_range": "8-14", "rate_per_day": 50, "currency": "USD"},
      {"day_range": "15-21", "rate_per_day": 100, "currency": "USD"}
    ]
  },
  "total_estimated": {
    "demurrage": 525,
    "detention": 350,
    "combined": 875,
    "currency": "USD"
  }
}
```

**Use Cases:**
- Freight forwarders estimating penalty costs before booking
- AI agents optimizing container pickup schedules to minimize charges
- Logistics companies comparing cost of delays across ports

---

### 2. GET /api/dd/compare
Compare demurrage & detention charges across multiple shipping lines for the same port. This is the killer feature — no other API offers cross-line D&D comparison.

**Price:** $0.25 per request

**Query Parameters:**
- `port` (required) — Port code or name
- `container_type` (optional) — Container size, default "20GP"
- `days` (optional) — Number of days to compare, default 14

**Example Request:**
```
GET https://api.shippingrates.org/api/dd/compare?port=INMUN&container_type=20GP&days=14
```

**Example Response:**
```json
{
  "port": "INMUN",
  "container_type": "20GP",
  "days": 14,
  "comparison": [
    {
      "line": "MSC",
      "total_dd_cost": 875,
      "free_days_demurrage": 7,
      "free_days_detention": 7
    },
    {
      "line": "MAERSK",
      "total_dd_cost": 1050,
      "free_days_demurrage": 5,
      "free_days_detention": 4
    },
    {
      "line": "COSCO",
      "total_dd_cost": 650,
      "free_days_demurrage": 10,
      "free_days_detention": 7
    }
  ],
  "cheapest": "COSCO",
  "savings_vs_most_expensive": 400,
  "currency": "USD"
}
```

**Use Cases:**
- Choosing the cheapest shipping line to minimize D&D exposure
- Negotiating better free days with carriers using competitive data
- Risk assessment for import operations

---

### 3. GET /api/local-charges
Look up port local charges (THC, documentation fees, BL fees, etc.)

**Price:** $0.05 per request

**Query Parameters:**
- `port` (required) — Port code or name
- `line` (optional) — Filter by shipping line

**Example Request:**
```
GET https://api.shippingrates.org/api/local-charges?port=INMUN&line=MSC
```

---

### 4. GET /api/inland/search
Search for inland transport routes and availability.

**Price:** $0.03 per request

**Query Parameters:**
- `origin` (required) — Origin location
- `destination` (required) — Destination location

**Example Request:**
```
GET https://api.shippingrates.org/api/inland/search?origin=INMUN&destination=Delhi
```

---

### 5. GET /api/cfs
Container freight station tariffs and charges.

**Price:** $0.05 per request

**Query Parameters:**
- `port` (required) — Port code
- `line` (optional) — Shipping line

---

### 6. GET /api/inland
Inland haulage rates for door delivery.

**Price:** $0.05 per request

**Query Parameters:**
- `origin` (required) — Origin port/location
- `destination` (required) — Destination

---

### 7. GET /api/lines (FREE)
List all available shipping lines in the database.

**Example Response:**
```json
{
  "lines": ["MSC", "MAERSK", "COSCO", "HAPAG", "ONE", "EVERGREEN"]
}
```

---

### 8. GET /api/stats (FREE)
Database statistics and coverage.

---

### 9. GET /health (FREE)
Server health, version, and configuration.

---

## MCP Server Configuration

To connect ShippingRates as an MCP tool in Claude, Cursor, or any MCP-compatible client:

```json
{
  "mcpServers": {
    "shippingrates": {
      "url": "https://mcp.shippingrates.org/sse"
    }
  }
}
```

The MCP server exposes 9 tools matching the API endpoints above. AI assistants can call these tools directly to query shipping data.

## Payment Flow (for agent developers)

1. Agent calls any paid endpoint (e.g., GET /api/dd/calculate?line=MSC&port=INMUN)
2. Server returns HTTP 402 with payment terms in headers
3. Agent signs USDC payment using x402 client library
4. Agent retries same request with `X-PAYMENT` header containing signed proof
5. Server verifies payment via facilitator and returns data
6. Settlement is instant — USDC transfers on-chain

### x402 Client Libraries
- **TypeScript:** `@x402/fetch` or `@x402/axios` + `@x402/evm` + `@x402/svm`
- **Python:** `x402` package with httpx or requests
- **Go:** `x402` Go module

## Coverage
- **Shipping Lines:** 6 major carriers (MSC, Maersk, COSCO, Hapag-Lloyd, ONE, Evergreen)
- **Records:** 2,400+ verified tariff entries
- **Countries:** 9 countries across Asia, Middle East, and Africa
- **Data:** 100% manually verified from official carrier tariffs

## Wallet Addresses (for direct integration)
- **Base (EVM):** 0x8c9e0882b4c6e6568fe76F16D59F7E080465E5C8
- **Solana:** Gcv56hKWuEGmXheBpJxAwQxvX6QAMimZzzVrHaVCbNWE

## Support
- Website: https://shippingrates.org
- API Docs: https://api.shippingrates.org/.well-known/x402.json
- Built by SmartBiz AI (Pune, India)