​
概述

Skip Go API 的身份验证与授权通过 API key 管理。 本文档涵盖以下内容：
  1. 为什么你应该使用 API key
  2. 如何完成 key 的配置
  3. 如何在请求中使用该 key
API Key 已取代 client_id过去，我们使用通过请求参数传递的 client_id 来识别并验证集成方身份。该机制现已完全弃用。如果你当前仍在使用 client_id，应尽快迁移到 API key。（我们之所以进行这次迁移，是因为 client_id 不符合安全最佳实践；同时，由于它是在请求体中传递而不是通过请求头传递，我们也只能为其附加非常有限的功能。）

​
使用 API key 的优势

从技术上讲，即使没有 API key，你仍然可以访问 Skip Go API 的大部分基础功能。但使用 key 进行身份验证有很多明显优势：
  • 无速率限制：未在请求中传递有效 API key 的集成方，会受到严格的全局速率限制影响，并且该限制会与所有其他未认证用户共享。
  • 更优的手续费分成定价：默认情况下，未认证的集成方需要就其手续费收入支付 25% 的收入分成。使用 API key 完成认证的集成方，默认仅需支付更低的 20% 收入分成。
  • 可访问特权功能： 使用 API key 完成认证的集成方，将获得一些无法向公众开放的高级功能（例如 Gas 估算 API、通用余额查询 API 等）。
  • 获得你的交易量与收入统计数据： 已认证的集成方可以获得月度统计数据，包括总交换与转账交易量，以及已赚取的手续费收入金额。此外，还会获得用于报税的年度交易数据。

​
如何获取 API Key

​
1. 申请 API Key

在我们的 Discord 中提交支持工单，并告知客服你希望申请一个 API key。 请在申请中提供以下信息，以便我们了解你的项目：
  1. 你的姓名（或匿名昵称）以及联系方式（最好是 Telegram，也可以是 Email、Signal 等）
  2. 你的项目名称
  3. 用 1 到 2 句话简要介绍你的项目
Skip 的客服成员会为 Skip 与你的项目建立一个正式的沟通渠道（例如邮件线程或 Telegram 群组等）。

​
2. 安全保存 API Key

你应在创建 API key 后立即妥善保存。出于安全原因，我们不会在服务器中存储你的原始 API key，因此如果你遗失了它，我们也无法帮你找回。 请务必对 API key 保密。任何持有你的 API key 的人，都可以以你的身份向 Skip Go API 发起请求，使用你的速率额度、访问你的特权功能，并影响你的收入和交易量统计数据。

​
如何使用 API key

​
通过 REST API

你应在对 Skip Go API 的每一次调用中，通过 authorization HTTP 请求头传递你的 API key。 例如： 
curl -X 'POST' \
  'https://api.skip.build/v2/fungible/route' \
  -H 'accept: application/json' \
  -H 'authorization: <YOUR API KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_in": "1000000",
  "source_asset_denom": "uusdc",
  "source_asset_chain_id": "axelar-dojo-1",
  "dest_asset_denom": "uatom",
  "dest_asset_chain_id": "cosmoshub-4",
  "cumulative_affiliate_fee_bps": "0",
  "allow_multi_tx": true
}'

​
通过 @skip-go/client

对于使用 @skip-go/client TypeScript 包（v1.0.0+）的用户，你可以在初始化时通过 setApiOptions 或 setClientOptions 配置 API key。该库会自动将其添加到所有请求的 authorization 请求头中。 例如： 
import { setApiOptions, setClientOptions } from "@skip-go/client";

// Option 1: For basic API calls
setApiOptions({
	apiKey: <YOUR API KEY>,
});

// Option 2: For executeRoute functionality
setClientOptions({
	apiKey: <YOUR API KEY>,
	// ... other options like endpointOptions, aminoTypes, etc.
});
注意：SkipClient 类已在 v1.0.0 中移除。现在，你应在设置 API 选项后直接导入并使用各个独立函数。另请注意，为遵循 camelCase 命名约定，apiURL 已重命名为 apiUrl。

​
搭建代理以接收 Skip Go API 请求并添加 API Key

为了确保 API key 的安全与私密性，我们建议你将前端发出的 API 请求先代理到你自己的后端，再由后端在请求头中加入 API key，之后再将请求转发到 Skip Go API。 下面的代码片段展示了如何使用 Next.js/Vercel 实现这类代理。整个配置过程非常快。 
// This handler runs server-side in Vercel and receive requests from the frontend
// sent to APP_URL/api/skip

import type { NextApiRequest } from 'next';
import { PageConfig } from 'next';

import { API_URL } from '@/constants/api';

export const config: PageConfig = {
  api: {
    externalResolver: true,
    bodyParser: false,
  },
  runtime: 'edge',
};

export default async function handler(req: NextApiRequest) {
  try {
    const splitter = '/api/skip/';

    const [...args] = req.url!.split(splitter).pop()!.split('/');
    const uri = [API_URL, ...args].join('/');
    const headers = new Headers();
    if (process.env.SKIP_API_KEY) {
      headers.set('authorization', process.env.SKIP_API_KEY);
    }
    return fetch(uri, {
      body: req.body,
      method: req.method,
      headers,
    });
  } catch (error) {
    const data = JSON.stringify({ error });
    return new Response(data, { status: 500 });
  }
}

// This config maps the requests to APP_URL/api/skip to the handler we just defined
	rewrites: async () => [
    {
      source: "/api/skip/(.*)",
      destination: "/api/skip/handler",
    },
  ],
// other config...

// This configures your client to make requests to your proxy service instead of
// the standard Skip Go API backend directly
import { setApiOptions, setClientOptions } from '@skip-go/client';

const appUrl =
  process.env.NEXT_PUBLIC_VERCEL_ENV === 'preview' ||
  process.env.NEXT_PUBLIC_VERCEL_ENV === 'staging'
    ? typeof window !== 'undefined'
      ? `https://${window.location.hostname}`
      : process.env.NEXT_PUBLIC_VERCEL_URL
    : 'https://<YOUR APP URL>';

// Option 1: For basic API calls
setApiOptions({
  // you don't need to pass apiKey since you already have it in your proxy handler
  apiUrl: `${appUrl}/api/skip`,
});

// Option 2: For executeRoute functionality
setClientOptions({
  // you don't need to pass apiKey since you already have it in your proxy handler
  apiUrl: `${appUrl}/api/skip`,
  // ... other options if needed
});

// These are environment variables you set in Vercel
// to store your API key securely in the backend
SKIP_API_KEY=<YOUR API KEY>

​
如何申请交易量与收入统计数据

只需回到你与 Skip 的正式沟通渠道（通常是某个 Telegram 频道）并提出数据申请。我们可以分享月度报告。未来我们还会提供带仪表盘的客户门户，届时你将能够以自助方式访问所需的全部数据。
有问题或反馈？帮助我们做得更好！加入 我们的 Discord，并选择 “Skip Go Developer” 角色来提交你的问题与反馈。

​
Summary

Authentication and authorization for the Skip Go API are managed via API keys. This document covers:
  1. Why you should use an API key
  2. How to get your key set up
  3. How to use the key in your requests
API Keys have replaced client_idHistorically, we used the client_id passed as a request parameter to identify and authenticate integrators. This system has been fully deprecated. If you’re currently using client_id, you should transition to using an API key.(We’re making this transition because client_id didn’t abide by best practices for security, and we could only attach limited functionality to it, since it was passed in the request body instead of a header.)

​
Benefits of using an API key

Technically, you can access most of the basic functionality of the Skip Go API without an API key. But there are numerous benefits to authenticating yourself with a key:
  • No rate limit: Integrators that do not pass a valid API key in their requests will be subject to a restrictive global rate limit, shared with all other unauthenticated users.
  • Improved fee revenue share pricing: Unauthenticated integrators will be subject to a 25% revenue share on their fee revenue by default. Authenticated integrators who use API keys will be subject to a cheaper 20% revenue share by default.
  • Access to privileged features: Integrators who authenticate with an API key will receive access to premium features that we cannot offer to the general public (e.g. Gas estimation APIs, universal balance query APIs, etc…)
  • Metrics on your volume and revenue: Authenticated integrators will receive access to monthly statistics regarding their total swap and transfer volume and the amount of fee revenue they’ve earned. They will also receive annual transaction data for taxes.

​
How to get an API Key

​
1. Request an API Key

Open a support ticket on our Discord and tell our customer support that you’d like an API key. Please provide the following information in your request to help us get to know your project:
  1. Your name (or pseudo-anon name) and contact info (ideally Telegram, but possibly Email, Signal, etc…)
  2. Your project name
  3. A brief, 1-2 sentence description of your project
The customer support team member at Skip will establish an official channel of communication between Skip and your project (e.g. an email thread or a telegram group etc…).

​
2. Store the API Key Securely

You should store the API key immediately when you create it. We do not store your raw API key in our server for security reasons, so we will not be able to access it for you if you lose it. It is important to keep your API key private. Anyone with your API key can make requests to the Skip Go API as you, getting access to your rate limit, privileged features, and affecting your revenue and volume statistics.

​
How to use an API key

​
Via REST API

You should pass your API key in every call to the Skip Go API using the authorization HTTP header. For example: 
curl -X 'POST' \
  'https://api.skip.build/v2/fungible/route' \
  -H 'accept: application/json' \
  -H 'authorization: <YOUR API KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_in": "1000000",
  "source_asset_denom": "uusdc",
  "source_asset_chain_id": "axelar-dojo-1",
  "dest_asset_denom": "uatom",
  "dest_asset_chain_id": "cosmoshub-4",
  "cumulative_affiliate_fee_bps": "0",
  "allow_multi_tx": true
}'

​
Via @skip-go/client

For users of the @skip-go/client TypeScript package (v1.0.0+), you can configure your API key using either setApiOptions or setClientOptions at initialization. The library will automatically include it in the authorization header of all requests. For example: 
import { setApiOptions, setClientOptions } from "@skip-go/client";

// Option 1: For basic API calls
setApiOptions({
	apiKey: <YOUR API KEY>,
});

// Option 2: For executeRoute functionality
setClientOptions({
	apiKey: <YOUR API KEY>,
	// ... other options like endpointOptions, aminoTypes, etc.
});
Note: The SkipClient class has been removed in v1.0.0. Instead, you import and use individual functions directly after setting the API options. Also note that apiURL has been renamed to apiUrl to follow camelCase conventions.

​
Setup a Proxy to Receive Skip Go API Requests and Add the API Key

To keep your API key secure and private, we recommend that you proxy the API requests from the frontend to your own backend—where you can add your API key in the header before forwarding the request to the Skip Go API. The snippets below show you how to use Next.js/Vercel for this kind of proxying. It only takes a moment to set up. 
// This handler runs server-side in Vercel and receive requests from the frontend
// sent to APP_URL/api/skip

import type { NextApiRequest } from 'next';
import { PageConfig } from 'next';

import { API_URL } from '@/constants/api';

export const config: PageConfig = {
  api: {
    externalResolver: true,
    bodyParser: false,
  },
  runtime: 'edge',
};

export default async function handler(req: NextApiRequest) {
  try {
    const splitter = '/api/skip/';

    const [...args] = req.url!.split(splitter).pop()!.split('/');
    const uri = [API_URL, ...args].join('/');
    const headers = new Headers();
    if (process.env.SKIP_API_KEY) {
      headers.set('authorization', process.env.SKIP_API_KEY);
    }
    return fetch(uri, {
      body: req.body,
      method: req.method,
      headers,
    });
  } catch (error) {
    const data = JSON.stringify({ error });
    return new Response(data, { status: 500 });
  }
}

// This config maps the requests to APP_URL/api/skip to the handler we just defined
	rewrites: async () => [
    {
      source: "/api/skip/(.*)",
      destination: "/api/skip/handler",
    },
  ],
// other config...

// This configures your client to make requests to your proxy service instead of
// the standard Skip Go API backend directly
import { setApiOptions, setClientOptions } from '@skip-go/client';

const appUrl =
  process.env.NEXT_PUBLIC_VERCEL_ENV === 'preview' ||
  process.env.NEXT_PUBLIC_VERCEL_ENV === 'staging'
    ? typeof window !== 'undefined'
      ? `https://${window.location.hostname}`
      : process.env.NEXT_PUBLIC_VERCEL_URL
    : 'https://<YOUR APP URL>';

// Option 1: For basic API calls
setApiOptions({
  // you don't need to pass apiKey since you already have it in your proxy handler
  apiUrl: `${appUrl}/api/skip`,
});

// Option 2: For executeRoute functionality
setClientOptions({
  // you don't need to pass apiKey since you already have it in your proxy handler
  apiUrl: `${appUrl}/api/skip`,
  // ... other options if needed
});

// These are environment variables you set in Vercel
// to store your API key securely in the backend
SKIP_API_KEY=<YOUR API KEY>

​
How to Request Volume & Revenue Statistics

Just return to your official communication channel with Skip (probably a Telegram channel) and request the data. We can share monthly reports. Eventually, we will create a customer portal with dashboards, so you’ll have access to all the data you need in a self-service manner.
Have questions or feedback? Help us get better!Join our Discord and select the “Skip Go Developer” role to share your questions and feedback.