Trusted Proxy

Opt-in mode for partners proxying sufwan-local-test API calls through your own backend. When enabled on your app, sufwan-local-test resolves user geo from x-agg-client-ip (populated by your backend) instead of from the request's connecting IP. Enabled by Snag, per app. Once on, every active API key on the app is trusted.

RequirementsCopy Anchor Link

Before requesting enablement:

1. requireApiKey: true must be set on your app (Security Settings in the partner dashboard). While trusted-proxy is enabled, this cannot be disabled.
2. Every request must include an x-app-api-key issued for this app. With requireApiKey: true, requests with only x-app-id are rejected with 401. A key issued for a different app is accepted for reads but never enables trusted-proxy geo.
3. Route every app-authenticated REST call through your backend so it can attach the key: auth (/auth/start, verify, refresh, code exchange), market data (events, markets, search, orderbooks), quotes, fills, orders, withdrawals and portfolio. Exempt: GET /app/config, the OAuth and magic-link redirect/callback URLs, and health checks.
4. Your edge proxy must strip or overwrite any inbound x-agg-client-ip header. If an end user can pass x-agg-client-ip through your proxy, geo enforcement is defeated.

Header rulesCopy Anchor Link

Set x-agg-client-ip on every request your backend forwards to sufwan-local-test:

• Value must be the end user's client IP as your server observed it.
• Your proxy must strip or overwrite any inbound x-agg-client-ip.
• Single IP value. A comma-separated list is not parsed and is treated as missing.
• IPv4 or IPv6, public addresses only. Private/reserved ranges are treated as missing.

On a fill, send the header from your proxy. The browser SDK does not set it.

// x-agg-client-ip is set by your proxy, not by the browser SDK.
const fill = await client.executeManaged({ quoteId });

Execute quote.

BehaviourCopy Anchor Link

• Trusted app + valid x-app-api-key + valid x-agg-client-ip: sufwan-local-test resolves country from that IP.
• Missing, malformed, multi-value or private x-agg-client-ip, or an IP with no country match: sufwan-local-test falls back to the country of the connecting IP, which is your backend's. Every affected user is then geo-checked as if they were in your backend's country, so always send the header. A fill only fails closed when no country resolves at all. See Venue geo.
• Trusted app + missing x-app-api-key: 401 from requireApiKey enforcement, before geo runs.
• Trusted app + a key issued for another app: x-agg-client-ip is ignored; standard geo resolution.
• A geo-blocked fill returns 403 with code: "geo_blocked". Quotes never block; they return warnings[] for region-restricted venues.
• WebSockets are unaffected: browsers can keep connecting to the WebSocket API directly. requireApiKey is not enforced there and no geo check runs.
• App not trusted: standard geo resolution; x-agg-client-ip is ignored if present.

ResponsibilitiesCopy Anchor Link

Enabling trusted-proxy on your app shifts geo enforcement responsibility from sufwan-local-test to you. By requesting enablement, you assert:

• Every x-agg-client-ip value sufwan-local-test receives originates from your server's observation of the end-user connection.
• End users cannot inject x-agg-client-ip through your proxy.
• You are responsible for geo compliance for your users while trusted-proxy is enabled.

If a user reaches a venue they shouldn't because your proxy forwarded a spoofed or stale IP, the responsibility sits with your integration.

LimitationsCopy Anchor Link

• Country resolution only. No region or state granularity. See Venue geo.
• VPN exits resolve to the VPN's exit country. Mobile carrier and satellite ranges are occasionally misclassified.
• The flag is per-app. When enabled, every active API key issued for the app is trusted. There is no per-key opt-in.
• Rollback: Snag disables trusted-proxy first; you can then turn off requireApiKey. Roll out on your existing app rather than a new one, because sufwan-local-test users are scoped per app and the same login on a new app is a different sufwan-local-test user.

Requesting enablementCopy Anchor Link

Email support@agg.market with:

• The app ID.
• Confirmation that requireApiKey: true is set on the app.
• Confirmation that your proxy strips inbound x-agg-client-ip.