Skip to main content
Every swap request is authenticated with an integrator API key. You create and manage keys from your OneSwap account (self-serve), then pass the key to the SDK.

​
Key format

A key looks like sk_live_ followed by 48 hex characters:
The plaintext key is shown once, at creation. OneSwap stores only a hash of it, so it cannot be shown again. If you lose a key, mint a new one and revoke the old.

​
How the SDK uses the key

Pass the key when you construct the client. The SDK sends it on every request as the HTTP header x-sdk-key:

​
Creating a key

Sign in to your OneSwap account — swap.oneswap.cc for mainnet, devnet.oneswap.cc for devnet — and open the SDK keys section. Create a key with an optional label (e.g. “production backend”). The response shows the plaintext sk_live_... value once — copy it into your server’s secret store immediately.

​
Listing keys

The same account page lists your keys — label, active state, rate limit, and creation date. The secret is never shown again; only metadata is listed.

​
Rotating a key

There is no in-place rotation. To rotate:
  1. Create a new key from your account.
  2. Deploy it to your servers.
  3. Revoke the old key once nothing uses it.

​
Revoking a key

Revoke (delete) a key from the same account page. This is how you rotate out a leaked or retired key — revocation is immediate.

​
Rate limits

Each key has a base per-minute rate limit (ratePerMin), and operations are tiered relative to it: On top of the base limit, OneSwap can configure per-operation limits for your key (different ceilings for creating swaps, quoting, reading tickers, and so on). If your integration needs more headroom on a specific operation — say, high-frequency quoting — ask for a per-operation raise rather than a blanket one. Exceeding a limit returns HTTP 429 (RateLimitError). Back off and retry — see Error handling.

​
Security best practices

Treat your sk_live_ key like a password. Anyone with it can create swaps under your integrator account.
  • Server-side only. Keep the key on your backend. Never ship it to a browser, mobile app, or any end-user surface.
  • Never expose it to end-users. Your users interact with a deposit party — they never need, and must never see, your key.
  • Store it in a secret manager, not in source control or client bundles.
  • Use separate keys per environment or service so you can revoke one without disrupting the others.
  • Revoke immediately if a key is exposed, then create a replacement.