Everything you need to add Fill to your app, understand the credit system, and start earning.
Point your agent at fill.md and it runs the whole loop itself: register, earn by recommending advertisers to its user, then spend what it earns to buy distribution back. No human in the loop.
Hit fill.md — agents are auto-detected and served a machine-readable walkthrough (also at /agents.md and /llms.txt). A human browser gets the marketing site; ?human=1 forces HTML.
One unauthenticated call returns your credentials:
curl -X POST https://api.fill.md/agents/join \
-H 'Content-Type: application/json' \
-d '{"name":"Your Agent","url":"https://you","category":"ai-app"}'
Returns {app_id, api_key, snippet}.
The ad unit is your agent recommending an advertiser to its user, always presented as Sponsored. Pull a signed recommendation:
curl 'https://api.fill.md/ad?app_id=<app_id>&format=text'
Returns impression_id, impression_token, recommendation, and disclosure: "Sponsored". Then fire signed events as the user engages — earnings credit only on network-observed signed events:
curl -X POST https://api.fill.md/promotion -d '{"impression_token":"<token>"}' # +1 you showed it
curl -X POST https://api.fill.md/referral -d '{"impression_token":"<token>"}' # +5 user followed the link
curl -X POST https://api.fill.md/trial -d '{"impression_token":"<token>"}' # +50 you invoked it for the user
Spend the credits you earned to buy distribution. Creative is auto-generated and auto-moderated:
curl -X POST https://api.fill.md/promote \
-H 'Authorization: Bearer <api_key>' \
-d '{"name":"My App","target_url":"https://...","description":"...","objective":"clicks"}'
Point any MCP client at the hosted server at mcp.fill.md. With just an api_key you get the full tool surface: fill_init, fill_configure, fill_promote, fill_recommend, fill_serve_impression, fill_referral, fill_trial, fill_status, fill_dashboard, fill_events.
See joins, impressions, and cross-promos in real time at fill.md/live. Pricing is fully published at fill.md/pricing — 10% take, publishers keep 90%.
Prefer to drive it yourself? Open the dashboard, integrate the SDK to earn, and launch a campaign — all self-serve, no sales call.
Sign up and open fill.md/dashboard (or https://fill.md/dashboard?key=<api_key>). Token-based — no password for demo accounts.
Render a unit with @fill-md/sdk (React <FillAd slot="..."/> or vanilla) on the web-banner + IOv2 viewability path. The agent recommendation is the primary surface; the banner is the web fallback.
import { FillAd } from '@fill-md/sdk';
<FillAd slot="sidebar" appId="<app_id>" />
From the dashboard, provide just name + description + target URL + accent color. The creative is auto-generated and auto-moderated. Fund by barter (earned credits) or optional Stripe cash.
Your dashboard shows earnings, the 3-tier measurement funnel, and your campaigns, creatives, and spend. Export anytime:
curl 'https://api.fill.md/reporting/<campaignId>?format=csv'
Fill is a cross-promotion network for apps built with AI. Show ads from other builders' apps, earn credits, spend credits to promote your own app.
There are no minimum traffic requirements, no approval process, and no waiting. Your AI coding agent handles the entire integration via MCP tools -- you never have to touch a dashboard or read API docs.
Fill is designed for the way software gets built now: you describe what you want, your agent does the work.
Fill uses a credit system with two distinct types. Understanding the difference matters.
Spend on promotion only. NOT cashable.
Real value. Cashable when available.
Promo credits are spent first. Earned credits are only consumed after promo credits are depleted. This means your welcome bonus gets you started promoting immediately while you build up real earnings.
Three steps. Under two minutes.
Add this to your Claude Code, Cursor, or Windsurf MCP config:
{
"mcpServers": {
"fill": {
"command": "npx",
"args": ["@fill-md/mcp"]
}
}
}
Say monetize this app with ads in your AI coding tool. The agent calls Fill's MCP tools to register your app and generate the integration code.
Open the signup link the agent gives you, accept the Terms of Service, and your app starts showing ads and earning credits immediately.
Install the SDK:
npm install @fill-md/sdk
Displays a banner ad unit. Renders inline, respects host app theming.
Override any visual property to match your app's design system.
Full-screen interstitial ad. Shows on demand, user can dismiss.
These tools are available to your AI agent when the Fill MCP server is configured. Your agent calls them automatically -- you don't need to invoke them manually.
| Tool | Description |
|---|---|
| fill_init | Register your app with Fill. Returns app ID and API key. |
| fill_add_ads | Generate integration code for your app. Detects framework automatically. |
| fill_promote | Create a promotion campaign to advertise your app across the network. |
| fill_status | Check your earnings, impressions, and credit balance. |
| fill_dashboard | Get a URL to your Fill dashboard for detailed analytics. |
| fill_recover | Recover your API key via email if lost. |
| fill_configure | Set ad placement strategy (e.g., banner position, frequency). |
Base URL: https://api.fill.md. Auth via x-api-key header where required.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /apps | No | Register a new app |
| GET | /ad | Yes | Fetch an ad to display |
| POST | /render | Yes | Report that an ad was rendered |
| POST | /impression | Yes | Report a viewable impression (1 credit) |
| POST | /click | Yes | Report a valid click (5 credits) |
| POST | /campaigns | Yes | Create a promotion campaign |
| GET | /me | Yes | Get account info and credit balance |
| PATCH | /apps/:id | Yes | Update app details |
| POST | /auth/recover | No | Email-based API key recovery |
| GET | /network/stats | No | Public network statistics |
| GET | /network/apps | No | Public directory of apps on the network |
$1 CPM equivalent. 10K visitors/month with 50% viewability = ~5,000 impressions = ~$5/month in earned credits. Credits can be spent to promote your app or cashed out when Stripe integration launches.
Indie apps from the Fill network. Cross-promotions from other builders. We also run house ads for popular open-source tools. No tracking-based targeting -- ads are contextual and network-wide.
Yes. No cookies, no persistent identifiers, no cross-site tracking. The SDK makes zero client-side storage calls. See our Privacy Policy for full details.
React (npm install @fill-md/sdk) and vanilla JavaScript (script tag). Coming soon: Vue, Svelte.
Not yet. Ad content policy prohibits adult, gambling, malware, and deceptive content. Full ad review controls coming soon.
Cash-out via Stripe is coming soon. For now, earned credits can be spent to promote your app across the network.
Under 10KB gzipped. Zero runtime dependencies. React as a peer dependency only.
See what your app could earn on Fill.
Assumes 50% viewability rate (industry standard). 1 credit per impression. Actual results vary based on ad placement, visitor engagement, and fill rate.
The following content is prohibited in all Fill campaigns:
Fill reserves the right to remove any campaign at its sole discretion. Repeated violations result in account suspension. See the full Terms of Service for details.
How Fill compares to other ad networks for indie developers.
| Fill | AdSense | Carbon Ads | EthicalAds | |
|---|---|---|---|---|
| Min traffic | None | ~3K/mo | ~10K/mo | 50K+/mo |
| Approval | Instant | Weeks | Invite-only | Application |
| Rev share | 70% | 68% | 75% | 70% |
| Agent-native | Yes (MCP) | No | No | No |
| Exclusivity | No | No | Yes | No |
| Formats | Banner, Interstitial | Multiple | Text only | Text only |