Skip to main content

Keys and limits

Swap quotes and creation work without an API key. Include your integrator key for partner attribution, fees, and backend quotas.

Integrator key​

X-Integrator-Key: wg_...

Send it on requests made for your integration. Keep server keys on your backend; request a public-client key for browser or mobile apps.

Credential rules
  • X-API-Key is an accepted alias. Query-string keys are rejected with 401.
  • Invalid or revoked keys and suspended integrations return 401.
  • Keys share their integration's fee settings and company quotas.
  • Key and configuration changes can take up to one minute to apply.
  • Public-client keys support attribution and fees, but use IP quotas and cannot access reporting. They cannot be converted to server keys; issue a new server key instead.

Forwarding an end-user IP from your backend​

To manage limits per client, ask us to approve your backend's egress IP, then send:

X-Integrator-Key: wg_...
X-End-User-IP: 203.0.113.42

Use one IPv4 or IPv6 address from your trusted ingress, replacing any user-supplied value. Company limits still apply. Once forwarding is enabled, requests without the header share one client allowance.

Forwarding requirements

Forwarding requires an active confidential partner key and an approved server IP. It is disabled by default. Unapproved forwarding returns 403; an invalid address from an approved server returns 400.

Send one literal IP without a port, hostname, CIDR, zone identifier, or address chain. Equivalent IPv6 and IPv4-mapped addresses share an allowance. Clients sharing an IP also share its allowance.

Use X-End-User-IP, not X-Forwarded-For, CF-Connecting-IP, or X-Real-IP. Those headers belong to the infrastructure proxy configuration. Enabling forwarding does not automatically increase company limits.

Server access limits​

Read GET /v2/integrator/me with your key for current limits and usage. Contact us for more company or per-client capacity; a larger client allowance still fits within the company ceiling.

On 429, wait for Retry-After. X-RateLimit-Resource identifies the exhausted limit. Creation attempts can consume capacity even when refused.

Unfinished orders count within the returned openOrderWindowMinutes. They stop counting when completed, failed, expired, refunded, or older than that window. The funding deadline is separate: use the order's expiresAt.

Access response example

These values are illustrative; read your own response for active limits.

{
  "limits": { "requestLimitPerMin": 600, "createLimitPerMin": 30, "maxOpenOrders": 40 },
  "defaults": { "requestLimitPerMin": 600, "createLimitPerMin": 6, "maxOpenOrders": 5 },
  "quoteLimitPerMin": 60,
  "openOrderWindowMinutes": 30,
  "openOrders": 3,
  "keyRequestLimitPerMin": 600,
  "clientIpForwarding": {
    "enabled": true,
    "header": "X-End-User-IP",
    "limits": { "requestLimitPerMin": 600, "createLimitPerMin": 6, "maxOpenOrders": 5 }
  },
  "attribution": { "windowDays": 30, "totalOrders": 10, "attributedOrders": 8, "distinctIps": 6 }
}

All applicable limits must allow the request. A zero disables that individual limit only. Open-order usage includes the integration's public and revoked keys; rotating or revoking a key does not free its slots.

Reported client IPs are stored separately from the server IP. Reporting exposes aggregate attribution, not raw IPs or the approved-server list. See quota details.

Order ownership​

Save the sessionId returned at creation and send it for order reads and actions:

X-Session-ID: <returned-session-id>

Keep it private and out of URLs. An order ID alone does not grant access.

Other ways to access orders

?verify=<destination-address> grants read-only access to one order. It cannot authorize refunds or other actions. A missing order or invalid access proof returns 404.

Authenticated integrators may supply a valid sessionId at creation to group their own orders. It is not an idempotency key and does not prevent duplicate creation.

Your fee​

Your integration has a default fee and payout addresses for EVM, Solana, and Bitcoin sources. Configure the address for each source family you serve.

To override the fee on one quote or order, send a percentage up to 5:

{ "integratorFeePercent": 0.5 }

Quotes return integratorFee with the fee percent, amount in USD, and payout address, or null when no fee applies. Fees too small to cover their transfer cost are skipped.

Reporting​

RouteReturns
GET /v2/integrator/me{ integrator, stats, access }: profile, fees, activity, limits, and usage
GET /v2/integrator/orders{ orders }: recent attributed orders and fee status (none, projected, paid, skipped)

Both require a server key and cover the whole integration across its keys. Public-client keys return 403. These reporting routes are documented here rather than in the public OpenAPI contract.