diff --git a/.gitignore b/.gitignore index edcdd25..5d00ada 100644 --- a/.gitignore +++ b/.gitignore @@ -39,5 +39,8 @@ CLAUDE.md claude.md v4-sdk-baseline-assessment.md +# OMC session data +.omc/ + # Ignore external repositories v4-subgraph/ diff --git a/.omc/state/subagent-tracking.json b/.omc/state/subagent-tracking.json deleted file mode 100644 index d958c9b..0000000 --- a/.omc/state/subagent-tracking.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "agents": [], - "total_spawned": 0, - "total_completed": 0, - "total_failed": 0, - "last_updated": "2026-04-09T01:39:37.976Z" -} \ No newline at end of file diff --git a/docs/api/overview.md b/docs/api/overview.md index bb72cea..4063a11 100644 --- a/docs/api/overview.md +++ b/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. \ No newline at end of file +Default rate limits per partner: **10 rps**, burst **20**, **5,000,000 requests / month**. Custom limits available on request. diff --git a/docs/api/routing/_category_.json b/docs/api/routing/_category_.json new file mode 100644 index 0000000..1819910 --- /dev/null +++ b/docs/api/routing/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Routing API", + "position": 1, + "collapsed": false +} diff --git a/docs/api/routing/overview.md b/docs/api/routing/overview.md new file mode 100644 index 0000000..0d66f24 --- /dev/null +++ b/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. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 5628643..5d3c00c 100644 --- a/docusaurus.config.ts +++ b/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 [] } diff --git a/sidebars.js b/sidebars.js index 95d45f7..803973e 100644 --- a/sidebars.js +++ b/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',