Api rate limits and api key requirements

docs.json

@@ -63,6 +63,7 @@
             "group": " ",
             "pages": [
               "references/api/overview",
+              "references/api/api-keys",
               {
                 "group": "Core Concepts",
                 "pages": [

features/fee-sponsorship.mdx

@@ -15,7 +15,7 @@ Fee sponsorship covers all destination chain fees (including gas topup amounts),
 
 Before you can sponsor transactions, you need:
 
-1. **An API Key** — Required to authenticate your sponsorship requests and associate them with your app balance.
+1. **An API Key** — Required to authenticate your sponsorship requests and associate them with your app balance. [Request an api key](/references/api/api-keys#how-to-get-an-api-key).
 2. **Enterprise Partnership** — Reach out to the Relay team to become an Enterprise Partner. Learn more about the [Enterprise Partner Program](/resources/enterprise).
 3. **A Linked Funding Address** — A wallet address must be linked to your API key. This is the address that will fund your app balance. [Reach out](https://forms.gle/XNeELYavjwoJwPEf7) to the relay team to link your wallet address.
 3. **Sufficient App Balance** — Your app balance must have enough funds to cover the fees you wish to sponsor.

references/api/api-keys.mdx

@@ -0,0 +1,98 @@
+---
+title: "Rate Limits and API Keys"
+---
+
+Relay enforces rate limits to ensure platform reliability and fair usage across integrators. Default limits apply to all requests. Higher limits are available via API keys.
+
+## Default Rate Limits (No API Key)
+
+The following limits apply when no API key is provided:
+
+| Endpoint | Limit |
+| --- | --- |
+| `/quote` | 50 requests per minute |
+| `/requests` | 200 requests per minute |
+| `/transactions/status` | 200 requests per minute |
+| Other endpoints | 200 requests per minute |
+
+## API Key Rate Limits
+
+When using an API key, limits increase and are applied per key:
+
+| Endpoint | Limit |
+| --- | --- |
+| `/quote` | 10 requests per second |
+| `/requests` | 10 requests per second |
+| `/transactions/status` | 10 requests per second |
+| Other endpoints | 200 requests per minute |
+
+API keys are recommended for production integrations and higher-throughput use cases.
+
+## How to Get an API Key
+
+To request an API key:
+
+1. Fill out the [API key request form](https://forms.gle/uiRVYXhtH8uBqybR9).
+2. The Relay team will review and provision your key within 72 hours.
+
+Once approved, you will receive a unique API key tied to your integration.
+
+
+## How to Use an API Key
+
+### HTTP Requests
+
+Pass the API key in the request headers:
+
+```
+x-api-key: YOUR_API_KEY
+```
+
+This header should be included on all requests where higher rate limits are required.
+
+### SDK Usage
+
+<CodeGroup>
+```jsx Global API Key
+// It is recommended to only set the apiKey parameter when using the SDK server-side.
+import {
+  createClient,
+  MAINNET_RELAY_API,
+} from "@relayprotocol/relay-sdk";
+
+createClient({
+  baseApiUrl: MAINNET_RELAY_API,
+  apiKey: "YOUR_API_KEY",
+  ...
+  //other parameters
+});
+```
+```jsx SDK Action API Key
+// In the case that you prefer not to set a global api key 
+// you can pass the api key into the headers parameter of the getQuote function. 
+import { getClient } from "@relayprotocol/relay-sdk";
+
+const quoteParams = {...}
+
+const quote = await getClient()?.actions.getQuote(params, undefined, {
+	"x-api-key": "YOUR_API_KEY"
+});
+```
+</CodeGroup>
+
+### Proxy API
+
+If using the sdk on the client, create a proxy api which appends the key in the headers and then pass that endpoint into the `baseApiUrl` parameter. This prevents your key from being leaked while allowing you to set up the necessary protection in your proxy api.
+
+```jsx
+import {
+  createClient,
+  MAINNET_RELAY_API,
+} from "@relayprotocol/relay-sdk";
+
+createClient({
+  baseApiUrl: "https://my-proxy.relay.link", //Replace with your proxy endpoint
+  ...
+  //other parameters
+});
+```

references/api/api_guides/bridging-integration-guide.mdx

@@ -3,6 +3,8 @@ title: "Bridging Integration Guide"
 description: "How to Integrate Bridging using Relay"
 ---
 
+import GetAnApiKey from "/snippets/GetAnApiKey.mdx";
+
 This guide shows you how to integrate the Relay API for bridging and onboarding.
 
 ## Get a Quote
@@ -65,6 +67,8 @@ quote = response.json()
 
 </CodeGroup>
 
+<GetAnApiKey />
+
 ### Quote Response Structure
 
 The quote response contains all information needed to execute the bridge:

references/api/api_guides/calling-integration-guide.mdx

@@ -3,6 +3,8 @@ title: "Call Execution Integration Guide"
 description: "How to execute cross-chain calls using Relay"
 ---
 
+import GetAnApiKey from "/snippets/GetAnApiKey.mdx";
+
 You can use Relay cross-chain execution to perform any action (tx) on any chain. This works by specifying the transaction data you wish to execute on the destination chain as part of the initial quoting process.
 
 ### Contract Compatibility
@@ -87,9 +89,10 @@ response = requests.post('https://api.relay.link/quote/v2', json={
 
 quote = response.json()
 ```
-
 </CodeGroup>
 
+<GetAnApiKey />
+
 ### Contract Interaction with Web3
 
 When calling smart contracts, you'll need to encode the function call data. Here's how to do it with popular libraries:

snippets/GetAnApiKey.mdx

@@ -0,0 +1,3 @@
+<Tip>
+To get a higher rate limit, you can [request an API key](/references/api/api-keys#how-to-get-an-api-key).
+</Tip>