Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shadowfeed.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
Step 1 — Sign in with your Stacks wallet

1

Visit shadowfeed.app

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

Connect wallet

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

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)

FieldRequiredNotes
HandleYesURL slug, 3-32 chars, lowercase + numbers + hyphens. Becomes /providers/handle.
Display nameYesShown on your profile + agent UI
DescriptionNoOne-sentence pitch
WebsiteNoLinked 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)

Pick this if you already have a production API.Required: partner endpoint URL (e.g. https://api.yourcompany.com). This is where ShadowFeed will send signed requests when an agent buys your feeds.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)

FieldRequiredNotes
Feed slugYesUnique per provider, e.g. whales, gas-prices
Display nameYesE.g. “Whale Alerts”
DescriptionNoHelps agents discover your feed
Price (STX)YesPer-query cost. Suggested: 0.003 - 0.05 STX
Source pathPartner BridgeRelative path on your API, e.g. /v1/whales
Source typeHosted Mirrorgithub_raw, r2_url, webhook_push, manual_upload
Source URLHosted Mirror pollingHTTPS URL to fetch JSON from
Poll intervalHosted Mirror polling60s, 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 runtimeHow to set the secret
Cloudflare Workerswrangler secret put SHADOWFEED_PARTNER_SECRET
VercelDashboard → Settings → Environment Variables
Railway / Fly.ioProject → Variables → Add
RenderService → Environment → Add Environment Variable
AWS LambdaConsole → Configuration → Environment variables
Docker / VPS.env file loaded by your process, or systemd EnvironmentFile
Herokuheroku 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: 
const secret = process.env.SHADOWFEED_PARTNER_SECRET;
Continue to the HMAC Integration Guide for the full verifier middleware. 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).
1

Open the warning banner

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

Sign the linking challenge

The destination wallet signs a SIWS message proving ownership.
3

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

Once your verifier is deployed and the env var is set, trigger a paid request: 
# Without payment — should return 402 with payment requirements
curl -i https://api.shadowfeed.app/feeds/p/your-handle/feed-slug
Use the ShadowFeed Agent SDK for the full pay-per-call test: 
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:
1

STX settles on platform

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

ShadowFeed forwards HMAC-signed request

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

Your middleware verifies + serves

Middleware validates signature, your route returns data.
4

Revenue credited

97% of the price lands in your pending_revenue counter.
5

Dashboard updates

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

​
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.