API Keys & Integrator ID

What Are They?

Production use of Across requires two credentials:

Credential	What it is	How it's used
API Key	Authentication token for API requests	Passed in the `Authorization` header on every API call
Integrator ID	Unique 2-byte hex identifier (e.g., `0xdead`)	Passed as a query parameter (`integratorId`) in API calls, or appended to calldata for direct contract integration

Both are required for production. Without them, your requests may be rate-limited or rejected.

How to Request

Request your API key and integrator ID by reaching out on Telegram. The team will provision your credentials and help you get set up.

Using with the Swap API

When calling the Swap API, pass both your API key in the Authorization header and your integrator ID as a query parameter:

swap-api-auth.ts

const params = new URLSearchParams({
  tradeType: "minOutput",
  originChainId: "42161",
  destinationChainId: "8453",
  inputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  outputToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  amount: "1000000000",
  depositor: "0xYourWalletAddress",
  integratorId: "0xdead",  // Your 2-byte hex integrator ID
});

const response = await fetch(
  `https://app.across.to/api/swap/approval?${params}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

Using with Direct Contract Integration

If you're calling depositV3 on the SpokePool directly (via the suggested-fees API), the credentials are passed differently:

API key — Authorization header on the /suggested-fees API call
Integrator ID — appended to the depositV3 transaction calldata (not as a query parameter)

Appending Integrator ID to Calldata

Append a delimiter (1dc0de) followed by your integrator ID to the end of the encoded depositV3 calldata:

Component	Value	Description
Delimiter	`1dc0de`	Fixed 3-byte hex string that marks the start of the identifier
Integrator ID	Your assigned ID (e.g., `f001`)	Unique identifier provided by the Across team

...0000000000000000000000000000000000000000000000000000000000000000  // last param
1dc0def001  // ← delimiter (1dc0de) + integrator ID (f001)

Do NOT pass the delimiter + identifier to any depositV3 parameter, including the message param. Only append it to the raw calldata of the transaction.

Do NOT use f001 as your identifier — it is an example only. Request your unique identifier from the Across team via your shared communication channel (Telegram, Slack) or email sales@across.to.

append-integrator-id.ts

import { encodeFunctionData, type Hex } from "viem";

const DELIMITER = "1dc0de";
const INTEGRATOR_ID = "f001";  // Replace with your assigned ID

// Encode depositV3 calldata normally
const calldata = encodeFunctionData({
  abi: spokePoolAbi,
  functionName: "depositV3",
  args: [depositor, recipient, inputToken, outputToken, inputAmount,
         outputAmount, destinationChainId, exclusiveRelayer,
         quoteTimestamp, fillDeadline, exclusivityDeadline, message],
});

// Append delimiter + integrator ID to the raw calldata
const calldataWithId = `${calldata}${DELIMITER}${INTEGRATOR_ID}` as Hex;

const hash = await walletClient.sendTransaction({
  to: spokePoolAddress,
  data: calldataWithId,
});

Testnet vs Production

Environment	Base URL	API Key Required?
Testnet	`https://testnet.across.to/api`	No
Production	`https://app.across.to/api`	Yes

Testnet does not require an API key or integrator ID. You can develop and test your integration freely on testnet without credentials. Only production requests need authentication.

Rate Limits

Without a valid API key, production requests are subject to strict rate limits. Authenticated requests receive higher rate limits appropriate for production traffic.

If you're seeing 429 Too Many Requests errors:

Verify your API key is included in the Authorization header
Check that the key is valid and not expired
Avoid polling /swap/approval or /suggested-fees more frequently than needed — these endpoints return fresh quotes, not cached data

Integrator ID Format

The integrator ID is a 2-byte hex string prefixed with 0x when used as a query parameter:

0xdead    ✓  Valid
0x0001    ✓  Valid
0xffff    ✓  Valid
dead      ✗  Missing 0x prefix
0xdeadbeef ✗  Too long (4 bytes)

When appending to calldata for direct contract integration, use the raw hex without the 0x prefix (e.g., dead not 0xdead).

API Keys & Integrator ID

On this page