Provider Onboarding

This guide walks you through registering as a ShadowFeed data provider. Estimated time: 5 minutes for sign-up, 30 minutes to wire up your HMAC verifier (Partner Bridge mode only).

Prerequisites

A Stacks wallet installed: Leather or Xverse
For Partner Bridge mode: an HTTPS endpoint you control (e.g. https://api.yourcompany.com)
For Hosted Mirror mode: a public JSON URL or willingness to push data via webhook

Visit shadowfeed.app

Open shadowfeed.app in a browser with Leather or Xverse extension installed.

Connect wallet

Click Connect Wallet → choose Leather or Xverse → approve in the popup.

Sign-In With Stacks

Click Providers in the nav → Become a Provider. Sign the SIWS challenge — this proves wallet ownership without exposing your private key.

Your wallet address becomes your provider account identity. You can link a different wallet for withdrawals later if revenue should go elsewhere (multisig, treasury, etc.).

Step 2 — Profile (wizard step 1)

Field	Required	Notes
Handle	Yes	URL slug, 3-32 chars, lowercase + numbers + hyphens. Becomes `/providers/handle`.
Display name	Yes	Shown on your profile + agent UI
Description	No	One-sentence pitch
Website	No	Linked from profile
X (Twitter)	No	`@handle` for community attribution

Reserved handles (admin, api, auth, dashboard, system, etc.) are blocked. Pick a handle specific to your brand.

Step 3 — Integration mode (wizard step 2)

Partner Bridge
Hosted Mirror

Pick this if you already have a production API — including one you already gate with x402 on Solana, Base, or another EVM chain. You point ShadowFeed at the same endpoint; it bypasses your existing paywall with an HMAC signature (see Coexisting with your existing x402 paywall).Required: partner endpoint URL — an origin only, e.g. https://api.yourcompany.com. No path, no trailing slash. The per-feed source_path (next step) is appended to this. Registering a path here (e.g. …/v1) is the most common cause of dead-on-arrival integrations.The wizard will generate an HMAC secret in step 4. Save it immediately — it’s shown once.

Step 4 — Add your first feed (wizard step 3)

Field	Required	Notes
Feed slug	Yes	Unique per provider, e.g. `whales`, `gas-prices`
Display name	Yes	E.g. “Whale Alerts”
Description	No	Helps agents discover your feed
Price (STX)	Yes	Per-query cost. Suggested: 0.003 - 0.05 STX
Source path	Partner Bridge	The exact route your server already serves, starting with `/` — e.g. `/whale-alerts`. ShadowFeed calls `partner_endpoint + source_path` and signs this path verbatim, so it must match a real route and must not repeat any segment already in `partner_endpoint`.
Source type	Hosted Mirror	`github_raw`, `r2_url`, `webhook_push`, `manual_upload`
Source URL	Hosted Mirror polling	HTTPS URL to fetch JSON from
Poll interval	Hosted Mirror polling	60s, 5min, 15min, or 1 hour

After submit, your provider goes from pending to active and the feed is live at /feeds/p/your-handle/feed-slug.

Step 5 — Save your HMAC secret

This step only applies to Partner Bridge mode. The wizard’s success screen shows the secret once. It looks like:

Z0rczxIVJuearIMIyAEy6solyqx2gCb4MKBhGqxcNEQ

You’ll see an integration guide right under the secret with copy-pasteable middleware code in three languages.

Copy the secret immediately. We only store a hash, so we cannot recover the plaintext if you lose it. If lost, rotate from the dashboard — but the old secret stops working instantly.

Step 6 — Where to put the HMAC secret

This is the most common point of confusion: on which server does the secret live? Answer: on the same server that hosts your partner_endpoint. Whatever domain/runtime serves the URL ShadowFeed will call.

Your `partner_endpoint` runtime	How to set the secret
Cloudflare Workers	`wrangler secret put SHADOWFEED_PARTNER_SECRET`
Vercel	Dashboard → Settings → Environment Variables
Railway / Fly.io	Project → Variables → Add
Render	Service → Environment → Add Environment Variable
AWS Lambda	Console → Configuration → Environment variables
Docker / VPS	`.env` file loaded by your process, or systemd EnvironmentFile
Heroku	`heroku config:set SHADOWFEED_PARTNER_SECRET=...`

The secret never gets put on ShadowFeed’s side as a user-facing config. We already store it as a hash for verification at signup time. You only manage it on your side.

After setting the env var, your code reads it via the standard mechanism:

TypeScript / Node
Cloudflare Workers
Python
Go

const secret = process.env.SHADOWFEED_PARTNER_SECRET;

const secret = c.env.SHADOWFEED_PARTNER_SECRET;

secret = os.environ["SHADOWFEED_PARTNER_SECRET"]

secret := os.Getenv("SHADOWFEED_PARTNER_SECRET")

Continue to the HMAC Integration Guide for the full verifier middleware.

Step 7 — Link a withdrawal wallet

Before you can withdraw STX, you must link a destination wallet. This can be the same wallet you signed in with, or a different one (multisig, treasury).

Open the warning banner

In the dashboard, click link one under the ”⚠ No linked withdrawal wallet” message.

Sign the linking challenge

The destination wallet signs a SIWS message proving ownership.

Verify

The dashboard now shows “Linked withdrawal: SP…”

Withdrawals can only go to this linked address. To change it later, sign a new linking challenge with the new wallet.

Step 8 — Verify end-to-end

First, run the free handshake test — before spending any STX. In the dashboard click Test connection (POST /providers/id/:id/hmac/test), or npx shadowfeed verify --endpoint https://api.you.com --secret "$SHADOWFEED_PARTNER_SECRET" if you use the SDK. It signs a request with your stored secret against your first feed’s source_path and probes your endpoint exactly like a real buyer would — catching secret and path mismatches in seconds. Don’t activate until this returns ok. Full breakdown: HMAC Integration → Verify your wiring. Then confirm the unpaid path returns a 402 challenge:

# Without payment — should return 402 with payment requirements
curl -i https://api.shadowfeed.app/feeds/p/your-handle/feed-slug

Finally, run one real pay-per-call test with the ShadowFeed Agent SDK:

import { ShadowFeed } from 'shadowfeed-agent';

const sf = new ShadowFeed({
  privateKey: process.env.AGENT_PRIVATE_KEY,
  network: 'mainnet',
});

const result = await sf.buy('p/your-handle/feed-slug');
console.log(result.data);

When the agent pays:

STX settles on platform

Agent’s STX transaction lands on the ShadowFeed platform wallet.

ShadowFeed forwards HMAC-signed request

Calls partner_endpoint + source_path with X-Sf-* headers.

Your middleware verifies + serves

Middleware validates signature, your route returns data.

Revenue credited

97% of the price lands in your pending_revenue counter.

Dashboard updates

Query log entry appears with TX hash linkable to Hiro Explorer.

Step 9 — Publish your discovery manifest

Publish a .well-known/shadowfeed-feeds.json file on your own domain. This is how marketplaces, partners, and grant reviewers independently confirm — from infrastructure you control — that you opted into ShadowFeed. ShadowFeed’s public verification endpoint (/providers/your-handle/manifest) fetches this file live and reports it under independence_attestation.well_known_manifest_present.

Using @shadowfeed/provider-sdk? This file is generated and served for you automatically from your registered feeds — skip straight to the verification commands below. The manual work here only applies to hand-rolled Partner Bridge integrations.

Serve it at the root of the same website domain you registered in Step 2:

https://yourdomain.com/.well-known/shadowfeed-feeds.json

It must resolve at the exact domain you registered — watch apex-vs-www redirects. If yourdomain.com 307-redirects to www.yourdomain.com and the file only lives on one of them, the check returns well_known_manifest_present: false. Always test the registered URL while following redirects: curl -IL https://yourdomain.com/.well-known/shadowfeed-feeds.json.

Use this shape — the live Hyre manifest is the reference implementation:

{
  "version": "1",
  "provider": {
    "name": "Your Company",
    "handle": "your-handle",
    "description": "One-sentence pitch.",
    "website": "https://yourdomain.com",
    "api": "https://api.yourdomain.com",
    "twitter_handle": "@your_handle",
    "contact_email": "you@yourdomain.com"
  },
  "partnerships": [
    {
      "marketplace": "shadowfeed",
      "marketplace_url": "https://shadowfeed.app",
      "marketplace_handle": "your-handle",
      "marketplace_verification_url": "https://api.shadowfeed.app/providers/your-handle/manifest",
      "integration_mode": "partner_bridge",
      "partner_endpoint": "https://api.yourdomain.com"
    }
  ],
  "feeds": [
    { "slug": "signal", "name": "Crypto Signal", "category": "signals", "path": "/signal", "method": "GET", "suggested_price_stx": 0.005 }
  ],
  "supported_payments": [
    { "scheme": "partner_bridge", "marketplace": "shadowfeed", "asset": "STX", "settlement_network": "stacks:mainnet" }
  ]
}

Each feeds[].path must match the source_path you registered in Step 4. If you cross-list on other marketplaces (x402scan, payai, etc.), add one entry per marketplace under partnerships so every partner can verify you from this single file. Verify it’s detected:

# Your file resolves at the registered domain (follow redirects)
curl -IL https://yourdomain.com/.well-known/shadowfeed-feeds.json    # expect: HTTP 200

# ShadowFeed sees it
curl -s https://api.shadowfeed.app/providers/your-handle/manifest \
  | grep well_known_manifest_present                                  # expect: true

What’s next

HMAC Integration Guide

Verifier code in TypeScript, Python, and Go — copy-paste ready.

Withdrawals & Revenue

Sign a withdrawal, link a wallet, view settlement history.

Troubleshooting

Common errors and how to fix them.

Provider dashboard

Live portal for managing feeds and revenue.

​Provider Onboarding

​Prerequisites

​Step 1 — Sign in with your Stacks wallet

​Step 2 — Profile (wizard step 1)

​Step 3 — Integration mode (wizard step 2)

​Step 4 — Add your first feed (wizard step 3)

​Step 5 — Save your HMAC secret

​Step 6 — Where to put the HMAC secret

​Step 7 — Link a withdrawal wallet

​Step 8 — Verify end-to-end

​Step 9 — Publish your discovery manifest

​What’s next

HMAC Integration Guide

Withdrawals & Revenue

Troubleshooting

Provider dashboard

Provider Onboarding

Prerequisites

Step 1 — Sign in with your Stacks wallet

Step 2 — Profile (wizard step 1)

Step 3 — Integration mode (wizard step 2)

Step 4 — Add your first feed (wizard step 3)

Step 5 — Save your HMAC secret

Step 6 — Where to put the HMAC secret

Step 7 — Link a withdrawal wallet

Step 8 — Verify end-to-end

Step 9 — Publish your discovery manifest

What’s next