HMAC Integration Guide
This guide adds HMAC request authentication to your API so it accepts signed requests from ShadowFeed and skips x402 payment for those calls.If you’re using Hosted Mirror mode (we host your data, no API server on your side), skip this entire guide. HMAC is only needed for Partner Bridge mode.
Already selling this data via x402 on Solana, Base, or another EVM chain? That’s the most common case. You do not stand up a new endpoint — you point ShadowFeed at the same API you already gate with x402. ShadowFeed adds a second payment rail (STX on Stacks) in front of it: the agent pays ShadowFeed in STX, and ShadowFeed proves itself to your server with an HMAC signature so your existing x402 paywall lets the call through for free. Your direct Solana/EVM buyers are unaffected. Read Coexisting with your existing x402 paywall before wiring anything.
TL;DR — 3 things to do
1
Grab your HMAC secret
From the provider dashboard or the success screen after onboarding.
2
Set it on your server
SHADOWFEED_PARTNER_SECRET=... as env var on your API server — not on ShadowFeed.3
Paste the middleware
Copy the snippet for your stack below. Mount BEFORE your x402 middleware.
How HMAC fits into the request flow
"" for GET requests.
Coexisting with your existing x402 paywall
If your endpoint is already gated by x402 (Solana, Base, other EVM), nothing about that setup changes. ShadowFeed becomes an additional, HMAC-authenticated caller in front of the same route:1
Run the HMAC check BEFORE your x402 middleware
A ShadowFeed call carries no x402 payment — it carries an
X-Sf-* signature instead. If your x402 middleware runs first, it returns 402 Payment Required to ShadowFeed before the HMAC verifier ever sees the request.2
On a valid signature, bypass the paywall and serve data
Set a flag (e.g.
skipX402) your payment middleware honors. On a missing or invalid signature, fall through to your normal x402 flow so your direct Solana/EVM buyers keep paying as usual.Setup checklist
- HMAC secret saved (from onboarding success screen or Rotate secret button)
- Decided which server hosts your
partner_endpoint - Set
SHADOWFEED_PARTNER_SECRET=your-secretas env var on that server - Confirmed your API can read the env var (
process.env,c.env,os.environ, etc.)
Verifier middleware
Pick the language tab matching your stack. All three implementations use the same canonical string format and are mutually compatible.- TypeScript / Workers
- Python / FastAPI
- Go / net/http
c.env.SHADOWFEED_PARTNER_SECRET, never visible in your code or logs.Mounted behind a prefix or an x402 router
x402 frameworks often mount everything under a prefix (e.g./api or /x402). When that happens, new URL(req.url).pathname includes the prefix — but ShadowFeed signed the path without it. Strip the known prefix before building the canonical string:
@shadowfeed/provider-sdk adapters do this for you — they reconstruct the signed path from the route parameter, so the canonical path is identical no matter where the router is mounted. If you can adopt the SDK, you skip this class of bug entirely.
Verify your wiring before going live
Do not make a real STX purchase your first test — it costs money and gives a vague pass/fail. Use a handshake test that signs and probes your endpoint exactly the way a buyer would, for free.- Dashboard (any stack)
- SDK CLI
In your provider dashboard, click Test connection (calls
POST /providers/id/:id/hmac/test). ShadowFeed signs a request with your stored secret against your first active feed’s source_path, fires it at partner_endpoint + source_path, and reports back:The response echoes
probed_path so you can confirm ShadowFeed is hitting the exact route you expect.pending_revenue counter. Confirm via the dashboard or GET /providers/id/your-id/analytics.
Common pitfalls
Building with Claude Code
If you use Claude Code to maintain your codebase, paste this prompt to bootstrap the integration:I want to integrate my API as a ShadowFeed external data provider. My stack is [Cloudflare Workers / FastAPI / Go / etc.]. I have the HMAC secret saved asClaude can read this doc, your codebase, and walk you through the wiring step-by-step.SHADOWFEED_PARTNER_SECRET. The full integration guide is at docs.shadowfeed.app/providers/hmac-integration. Walk me through:My API base URL is
- Adding the HMAC verifier middleware to my existing routes (preserve current x402 / auth)
- Setting the env var on my deployment platform
- Testing the integration end-to-end
https://api.mycompany.comand the feed I want to expose is at/v1/whales.
Reference
Canonical string
Headers sent by ShadowFeed
Signature algorithm
Next steps
Withdrawals & Revenue
How to cash out accumulated STX.
Troubleshooting
Debug HMAC failures, request issues.