docs: partner routing api

.gitignore

@@ -39,5 +39,8 @@ CLAUDE.md
 claude.md
 v4-sdk-baseline-assessment.md
 
+# OMC session data
+.omc/
+
 # Ignore external repositories
 v4-subgraph/

docs/api/overview.md

@@ -6,54 +6,27 @@ title: Overview
 
 ## Ring APIs
 
-Welcome to the Ring API documentation. Ring provides several APIs and data sources to help developers integrate with and build on top of the Ring protocol.
+The **Ring Routing API** is a partner-facing quote service. It returns the best executable swap quote on a given pair, with execution-ready calldata, routing across Ring Swap v2, Uniswap v3 / v4, and FewToken-wrapped pools — and optionally racing external aggregators (1inch, Bitget, Enso, HiUni) for best execution.
 
-## Available APIs
+## Quote API
 
-### Subgraph API
-The Ring Subgraph provides a GraphQL API for querying historical and real-time data from the Ring protocol.
+```
+POST https://gateway.ring.exchange/v1/partner/quote
+```
 
-- **[Subgraph Documentation](./subgraph/overview)** - Learn how to query Ring data using GraphQL
+Returns the optimal swap quote for a token pair, plus the router contract address and calldata to submit on-chain.
 
-### Routing API
-The Ring Routing API provides optimized trade routes and quotes for swaps.
+→ See the **[Routing API reference](./routing/overview)** for headers, request/response schema, supported chains, and examples.
 
-- **Smart Order Routing** - Find the best prices across multiple pools
-- **Gas Optimization** - Routes optimized for gas efficiency
-- **Multi-hop Support** - Complex routing across token pairs
+## Getting access
 
-### Price APIs
-Get real-time and historical price data for tokens in Ring-related markets and integrations.
+The Routing API is gated by an API key issued per partner. To request access, email **[contact@ring.exchange](mailto:contact@ring.exchange)** with:
 
-- **Current Prices** - Real-time token prices
-- **Historical Data** - Price charts and historical trends
-- **Pool Information** - Liquidity and volume data
+- Project name and website / app URL
+- A short description of how you plan to use the API
+- Estimated traffic (requests per day, peak rps if known)
+- Filler / executor contract address (if applicable)
 
-## Getting Started
+The Ring team will review and reply with your API key and assigned `x-partner-id` slug.
 
-### For Developers
-If you're building applications that need to:
-- Query historical trading data → Use the **Subgraph API**
-- Get optimal swap routes → Use the **Routing API**
-- Display token prices → Use the **Price APIs**
-
-### For Data Analysis
-The Subgraph API is perfect for:
-- Analytics dashboards
-- Trading strategy research
-- Protocol metrics and insights
-- DeFi research and analysis
-
-## Rate Limits and Usage
-
-- **Subgraph API**: Generous rate limits via The Graph
-- **Routing API**: Production-ready with caching
-- **Price APIs**: Real-time updates with historical data
-
-## Support and Resources
-
-- **Discord**: Join the Ring developer community
-- **GitHub**: Explore code examples and integrations
-- **Documentation**: Comprehensive guides and references
-
-Ready to start building? Choose the API that fits your needs from the navigation menu.
+Default rate limits per partner: **10 rps**, burst **20**, **5,000,000 requests / month**. Custom limits available on request.

docs/api/routing/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Routing API",
+  "position": 1,
+  "collapsed": false
+}

docs/api/routing/overview.md

@@ -0,0 +1,151 @@
+---
+id: overview
+sidebar_position: 1
+title: Routing API
+---
+
+# Ring Routing API
+
+A partner-facing quote endpoint that returns the best executable swap quote from Ring Protocol Pools.
+
+## Endpoint
+
+```
+POST https://gateway.ring.exchange/v1/partner/quote
+```
+
+A staging environment is available at `https://gateway.testring.org/v1/partner/quote` — coordinate with the Ring team before targeting it.
+
+## Authentication
+
+Every request requires three headers:
+
+| Header | Required | Description |
+|---|---|---|
+| `x-api-key` | Yes | Your partner API key. Issued by Ring — email [contact@ring.exchange](mailto:contact@ring.exchange) to request one (see [Getting access](#getting-access)). Treat as a secret; proxy through your backend, do not ship to end-user devices. |
+| `x-partner-id` | Yes | Your partner slug (lower-case), assigned during onboarding (e.g. `orbs`). The slug and key are cross-checked: a key issued to partner A cannot impersonate partner B. |
+| `Content-Type` | Yes | `application/json` |
+
+A missing or invalid `x-api-key` returns `403` (rejected by the gateway). A missing or mismatched `x-partner-id` returns `400` with `errorCode: VALIDATION_ERROR`.
+
+## Supported chains
+
+Currently **only Ethereum Mainnet (`chainId: 1`)** is supported. Additional chains will be enabled as they are reviewed and rolled out. Coordinate with the Ring team before targeting other chains.
+
+## Quick start
+
+```bash
+curl -X POST "https://gateway.ring.exchange/v1/partner/quote" \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "x-partner-id: YOUR_PARTNER_SLUG" \
+  -d '{
+    "tokenIn":  "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    "tokenOut": "0x0000000000000000000000000000000000000000",
+    "amount":   "1000000000101000000",
+    "tokenInChainId":  1,
+    "tokenOutChainId": 1,
+    "swapper": "0xYourFillerContractAddress",
+    "type": "EXACT_INPUT"
+  }'
+```
+
+### Required fields
+
+| Field | Description |
+|---|---|
+| `tokenIn` / `tokenOut` | Token addresses. Use `0x0000000000000000000000000000000000000000` for the chain's native asset (ETH). |
+| `amount` | Raw amount in the token's smallest unit (wei for ETH, 6-decimal units for USDT, etc.). For `EXACT_INPUT` this is the input amount; for `EXACT_OUTPUT` it's the desired output amount. |
+| `tokenInChainId` / `tokenOutChainId` | Chain ID. Both must equal `1` (Ethereum mainnet). |
+| `swapper` | **Your filler contract address.** Used to generate the calldata, and set as the recipient of the swap output. If wrong, the calldata won't match and output tokens will be sent to the wrong address. |
+| `type` | `EXACT_INPUT` or `EXACT_OUTPUT`. |
+
+### Optional fields
+
+| Field | Default | Description |
+|---|---|---|
+| `protocols` | `["FewV2"]` | Liquidity sources to consider for the route. Currently only `FewV2` is supported. |
+| `autoSlippage` | — | Set to `DEFAULT` for automatic slippage selection. |
+
+## Response
+
+A successful request returns HTTP `200`:
+
+```json
+{
+  "requestId": "fe67ff8b-79e7-46c7-84d3-b6816d2c136a",
+  "routing": "CLASSIC",
+  "quote": {
+    "chainId": 1,
+    "tradeType": "EXACT_INPUT",
+    "swapper": "0xYourFillerContractAddress",
+    "input": {
+      "amount": "1000000000101000000",
+      "token": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
+    },
+    "output": {
+      "amount": "405123456789",
+      "token": "0x0000000000000000000000000000000000000000",
+      "recipient": "0xYourFillerContractAddress"
+    },
+    "methodParameters": {
+      "to":       "0x24e743CcE93235641f2be8Ce7ffC6330903ab96f",
+      "calldata": "0x...",
+      "value":    "0"
+    },
+    "route": [ /* ordered list of pool hops */ ],
+    "slippage": 0.5,
+    "gasFee":    "662490501387712",
+    "gasFeeUSD": "1.59",
+    "gasUseEstimate": "63592",
+    "quoteId": "d21e3281-5f14-4a4c-8369-d1a7250fca9f"
+  },
+  "permitData": { /* Permit2 typed data, when input token requires approval */ }
+}
+```
+
+### What to grab from the response
+
+To execute the swap on-chain, take these three fields and submit a transaction:
+
+| Field | Use |
+|---|---|
+| `quote.methodParameters.to` | Router contract address — destination of your transaction |
+| `quote.methodParameters.calldata` | Encoded swap calldata — the `data` field of your transaction |
+| `quote.methodParameters.value` | Native token value to attach (in wei) — the `value` field of your transaction |
+
+If `permitData` is present, sign the Permit2 typed data first and submit the signature alongside the swap.
+
+The endpoint does **not** validate sender balances or token approvals — it only returns calldata. If you call it from a filler contract, make sure the contract has the input tokens (and required approvals) before submitting the transaction.
+
+### Other useful fields
+
+| Field | Description |
+|---|---|
+| `routing` | Routing mode used to produce the quote. Currently `CLASSIC`. |
+| `quote.input.amount`, `quote.output.amount` | Final input and output amounts (wei). |
+| `quote.slippage` | Effective slippage applied (percent). |
+| `quote.gasFee`, `quote.gasFeeUSD` | Estimated gas fee in wei and USD. |
+| `quote.route` | Ordered list of pool hops used for the quote. |
+| `quote.quoteId`, `requestId` | UUIDs — useful for support tickets and log correlation. |
+
+## Errors
+
+| Status | `errorCode` | Cause |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Missing or malformed field, missing `x-partner-id`, partner-id / API-key mismatch, unsupported chain. |
+| `403` | — | Missing or invalid `x-api-key`. Rejected at the gateway, never reaches the service. |
+| `404` | `NO_QUOTES_AVAILABLE` | No quoter returned a usable price for the requested pair. |
+| `429` | `TOO_MANY_REQUESTS` | Per-partner rate limit (default 10 rps / burst 20) or monthly quota (default 5M / month) exceeded. Honor `Retry-After`. |
+| `500` | varies | Upstream quoter failure. Retry with exponential backoff. |
+
+## Integration notes
+
+- **Token addresses**: use the checksummed ERC-20 contract address. For native ETH, use `0x0000000000000000000000000000000000000000`.
+- **Amounts** are strings in the token's smallest unit.
+- **Permit2**: when `permitData` is present in the response, sign the typed data with the swapper key and include the signature in your transaction. Without it, the swap will revert.
+- **`FewV2` routing**: quotes are sourced from Ring Protocol Pools and route through FewToken-wrapped liquidity, which can offer better pricing for certain pairs.
+
+## Getting access
+
+To request a partner API key, email **[contact@ring.exchange](mailto:contact@ring.exchange)** with your project name, website / app URL, intended use, and estimated traffic. The Ring team will review and reply with your API key and assigned `x-partner-id` slug.

docusaurus.config.ts

@@ -67,11 +67,11 @@ const config: Config = {
           docId: 'sdk/v2/overview',
           label: 'SDKs',
         },
-        // {
-        //   type: 'doc',
-        //   docId: 'api/subgraph/overview',
-        //   label: 'APIs',
-        // },
+        {
+          type: 'doc',
+          docId: 'api/overview',
+          label: 'APIs',
+        },
         {
           type: 'doc',
           docId: 'wallet/overview',
@@ -141,10 +141,8 @@ const config: Config = {
                   item.type === 'category' &&
                   (item.link?.id === 'contracts/the-compact/overview' ||
                     item.link?.id === 'contracts/protocol-fee/overview' ||
-                    item.link?.id === 'api/subgraph/overview' ||
                     item.label === 'The Compact' ||
-                    item.label === 'Protocol Fee' ||
-                    item.label === 'APIs')
+                    item.label === 'Protocol Fee')
                 ) {
                   return []
                 }

sidebars.js

@@ -44,20 +44,28 @@ const sidebars = {
         },
       ],
     },
-    // {
-    //   type: 'category',
-    //   label: 'APIs',
-    //   link: {
-    //     type: 'doc',
-    //     id: 'api/subgraph/overview',
-    //   },
-    //   items: [
-    //     {
-    //       type: 'autogenerated',
-    //       dirName: 'api',
-    //     },
-    //   ],
-    // },
+    {
+      type: 'category',
+      label: 'APIs',
+      link: {
+        type: 'doc',
+        id: 'api/overview',
+      },
+      items: [
+        {
+          type: 'category',
+          label: 'Routing API',
+          link: { type: 'doc', id: 'api/routing/overview' },
+          collapsed: false,
+          items: [
+            {
+              type: 'autogenerated',
+              dirName: 'api/routing',
+            },
+          ],
+        },
+      ],
+    },
     {
       type: 'category',
       label: 'Wallet',