Authentication and ownership
Wagyu uses the least broad credential that can authorize an action. The interactive reference marks the accepted schemes for every consumer route; do not substitute one credential type for another.
| Need | Credential | Where it is sent |
|---|---|---|
| Read or act on the orders in one browser flow | Session identifier | x-session-id header |
| Read one specific order without the session | Exact destination address | verify query parameter |
| Attribute orders to your integration and earn a fee on them | Integrator API key | x-integrator-key header |
Quoting, creating and tracking orders requires no API key. The key does not unlock the API; it identifies the orders as yours. See integrator key.
Order ownership
Every order creation response includes a sessionId. It is an owner credential: persist it and send it in the x-session-id header for owner reads and actions, including refund submission and coinflip decisions. Consumer clients omit it when creating an order; Core generates it. An integrator may supply a valid session value only to group its own orders, and must authenticate that request with a valid x-integrator-key or x-api-key; otherwise Core rejects the create request. An order ID alone authorizes nothing.
For a single read, ?verify=<destination-address> is an alternative read-only proof. It is the exact destination address, not a separately generated secret; it does not authorize mutations or access to the rest of the session. Verify-tier responses expose only public order fields.
The three single-order read routes intentionally return the same 404 response for a missing order and an invalid or absent credential, so clients must never infer whether an order ID exists from that response.
Never place a session ID in a shareable URL. See live updates for the browser WebSocket proof pattern and actions and retries for owner-action rules.
Integrator key
An integrator key is issued to an integration and sent on every request you want credited:
x-integrator-key: wg_...
One integration may hold several keys — one per app, environment or client — and they all share the integration's fee percent and payout addresses. Revoking one key leaves the others working; suspending the integration stops all of them.
x-api-key is accepted as an alias. A key in the query string is refused with 401 even if it is valid — ?apiKey= would deposit your credential in the logs of every proxy between you and Core. An invalid or revoked key is 401, and so is a valid key whose integration is suspended: Core never quietly downgrades the request to an anonymous one, because that would silently cost you the fee on a real order.
What the key changes:
| Without a key | With a key | |
|---|---|---|
| Quote, create, read, track orders | works | works |
| Attribution of the order to you | — | recorded on the order |
| Your fee on the order | — | collected and paid to your address |
Supplying your own sessionId at creation | 401 | allowed |
| Reporting routes below | 401 | allowed |
Your fee
Your integration carries a default fee percent and a payout address per source family (EVM, Solana, Bitcoin) — not the individual key, so every key you hold earns to the same addresses at the same rate. Core picks the address matching the order's source chain, so all three must be set for the chains you intend to serve.
Send integratorFeePercent on a quote or a create to override the integration's default for that one order. It is a percent, not basis points, and the maximum per request is 5:
{ "…": "…", "integratorFeePercent": 0.5 }
Quote responses echo what you will actually earn as integratorFee: { feePercent, feeAmountUsd, feeAddress }, or null when no key was sent or no payout address covers that source chain. A fee too small to be worth its own transaction is skipped rather than eating the customer's output; the order itself never waits on it.
Reporting
These two routes require the key and are the only ones that do. They are excluded from the generated OpenAPI document because they read your customers' orders, so their shapes are documented here:
| Route | Returns |
|---|---|
GET /v2/integrator/me | { integrator, stats } — your integration's profile and fee config, plus lifetime and 24h swap count, volume, fee earned, a 30-day daily series, and recent orders |
GET /v2/integrator/orders | { orders } — your most recent attributed orders, each with its fee status: none, projected, paid or skipped |
Both report on the integration, not on the one key you called with: if you hold several keys, each sees the whole integration's volume and orders.
A key marked as a public client — one shipped inside a mobile app or browser extension, where the key is extractable from the bundle — is refused on both with 403. It keeps everything else, including its own sessionId at creation, which is the privilege a self-custody wallet actually needs. Ask for that flag when your key will ship inside a distributed binary.