Two concepts: PUBLISH vs LIST — never confuse them
This skill handles two fundamentally different concepts. Mixing them up is the #1 source of wrong answers.
| Concept |
What it means |
Functions |
| PUBLISH (发布) |
Make something accessible — a URL works, or code is on GitHub |
publish_preview, unpublish_preview, list_published_previews, open_source, remove_open_source, list_open_source, get_open_source, fork, validate_open_source |
| LIST (上架) |
Make something discoverable/purchasable on the marketplace |
Free: list_in_dashboard, unlist_from_dashboard, delete_listing, get_listing_statusPaid: create_paid_service, submit_for_review, get_review_status, publish_service, unpublish_service, list_my_services, get_service, update_service, delete_service, restore_serviceCover: upload_cover_imageBrowse + consumer: explore_services, get_service_detail, get_service_pricing, get_service_reviews, write_service_review, favorite_service, unfavorite_service, get_favorite_services, get_user_services, get_service_earnings, get_earnings_summary, get_service_tags, get_featured_servicesProjects query: explore_projects, my_projects, favorite_projects, get_tab_counts, get_popular_tags, get_user_projects, favorite_project, unfavorite_project |
Publishing does NOT auto-list. publish_preview() only allocates the URL. open_source() only pushes code. Neither makes the project discoverable on the marketplace — that requires a separate, deliberate LIST call.
Listing has two flows
| Flow |
When to use |
Review? |
Pricing? |
Functions |
| Free listing |
Free project, show on /projects gallery |
No |
No |
list_in_dashboard() |
| Paid listing |
Charge for access via x402 |
Required (6-check review, must pass before publishing) |
Yes (USDC/USDG/USDC(Solana) on platform networks — default Base+Monad+Robinhood+X Layer+Solana, follows all) |
create_paid_service() → submit_for_review() (required) → publish_service() |
POST /api/services no longer accepts service_type: "free_project". Free listing is done by list_in_dashboard() (the project gallery flow). Paid listing uses create_paid_service() + review + publish (the service API flow).
Limited-time free promo ≠ this skill
After a paid service is listed, the owner may run a time-window free promotion
(free_promo_start / free_promo_end). That is not marketplace listing work and is
not implemented here.
| Concept |
What it is |
Where |
| Free listing |
Free project on /projects gallery |
this skill → list_in_dashboard() |
free_trial_count |
N free calls before charge (pay_per_use only) |
this skill → create_paid_service(..., free_trial_count=N) |
| Limited-time free promo |
Calendar window: amount-0 verify, no settle/debit |
x402 skill → skills/x402/references/selling.md section Limited-time free promotion |
If the user asks to “开限时免费 / free promo / free for N days” on an already-paid listing:
read the x402 skill (self-check P1–P5, then PUT free-promo). Do not invent APIs in
community-publish or confuse it with free_trial_count.
Visibility model — read this before answering "can others see it?"
A project's "publicness" is three orthogonal switches, not one:
| Switch |
Off state |
On state |
Flipped by |
| URL access |
Visiting the URL returns 404 |
URL works for anyone who has the link |
publish_preview / unpublish_preview |
| Gallery discoverability |
Not on /projects gallery |
Appears in the gallery |
list_in_dashboard / unlist_from_dashboard |
| Marketplace listing |
Not on the Service Marketplace |
Discoverable + purchasable |
create_paid_service + publish_service / unpublish_service |
A project can be in any combination. Never collapse these into "is it public yet".
Status questions are read-only operations. Whenever the user asks:
- "is it visible / public / discoverable yet?"
- "上架了吗 / 在 dashboard 上吗 / 别人能看到吗"
- "is the listing live?"
The authoritative answer comes ONLY from a fresh get_listing_status(slug) (free) or get_review_status(service_id) (paid) call. Do NOT infer from past actions.
Project types — three only
| type |
What it is |
Eligible for publish_preview()? |
task |
Scheduled cron/interval job |
No (no HTTP port) |
service |
Long-running HTTP service (dashboard, API, page) |
Yes |
script |
One-shot script |
No (no HTTP port) |
Routing — match user intent to the right action
A. Status intents — user wants to know current state
| Sample phrasing |
Action |
| "is it visible / public / discoverable / live?" |
get_listing_status(slug) |
| "上架了吗 / 在 dashboard 上吗 / 别人能不能看到" |
get_listing_status(slug) |
| "what URLs do I have published?" / "我发布了哪些" |
list_published_previews() |
| "what's open-sourced?" / "都有哪些开源代码" |
list_open_source(...) |
| "我的服务" / "my services" / "我的付费服务" |
list_my_services() |
| "审核状态" / "审核通过了吗" / "review status" |
get_review_status(service_id) |
B. Action intents — user wants to change state
| Sample phrasing |
Action |
Notes |
| "publish" / "share" / "make public" / "公开" / "发布" (no qualifier) |
publish_preview(preview_id) |
Allocates the URL only. Listing is NOT auto-flipped. |
| "list on the dashboard" / "上架" / "show on community" / "make discoverable" / "发到广场" |
list_in_dashboard(slug) |
Free listing. Requires the preview to already exist. |
| "上架付费服务" / "make this a paid service" / "上架到服务市场(付费)" |
create_paid_service(...) → submit_for_review() (recommended) → publish_service() |
Paid listing. Needs x402 config first. |
| "publish AND list" / "发布并上架" |
publish_preview() THEN list_in_dashboard() |
Two separate calls in order. |
| "remove from dashboard" / "下架" / "unlist" / "hide from gallery" |
unlist_from_dashboard(slug) |
Free listing only. Soft-unlist (sets is_public=false, review_status='unlisted', preserves stats). Preview URL stays alive. |
| "下架付费服务" / "unpublish service" |
unpublish_service(service_id) |
Paid listing only. |
| "open source" / "open-source the code" / "开源代码" |
open_source(project_dir) |
Pushes code to GitHub. Does NOT list. |
| "unpublish the URL" / "take down the link" / "停止服务" |
unpublish_preview(slug) |
Stops the preview container service only. Does NOT affect listing state (is_public/review_status unchanged). URL becomes inaccessible (404). |
| "remove the open source" / "delete from GitHub" |
remove_open_source(slug) |
|
| "fork" / "install someone's project" |
fork(source) |
|
| "提交审核" / "submit for review" |
submit_for_review(service_id) |
Paid only. Required — must pass before publishing |
| "发布服务" / "publish my service" |
publish_service(service_id) |
Paid only, requires approved or unlisted state |
| "更新服务" / "update service" |
update_service(service_id, ...) |
Paid only |
| "删除服务" / "delete service" |
delete_service(service_id) |
Paid only |
| "删除项目" / "delete listing" / "permanently remove from marketplace" |
delete_listing(slug) |
Free listing only. Permanently deletes the listing row AND the community_slugs record. URL becomes inaccessible (404). Removes from both explore and my-projects. Use unlist_from_dashboard() to hide without deleting. |
| Ambiguous after rereading |
Ask one question |
"你是要 (a) 发布公开 URL,(b) 免费上架到广场,(c) 付费上架到服务市场,还是 (d) 开源代码?" |
Cross-link via publisher: binding
When the same project has BOTH a public URL AND open-sourced code, you want them paired so the frontend renders "View Source" on the listing card and "Visit Live Demo" on the code card. This skill drives that pairing through one explicit binding in project.yaml.
How to declare the binding
Add a publisher: block to project.yaml:
name: my-app
type: service
version: 1.0.0
publisher:
code_slug: my-app # OPTIONAL — defaults to manifest.name
public_slug: my-app-pub # OPTIONAL — URL suffix; defaults to code_slug
Both fields are optional. If omitted, both default to manifest.name.
Either side can be published first
The gateway holds a pending entry until the second side arrives. No ordering requirement, no manual link step.
| Order |
What happens |
open_source first → publish_preview second |
open_source records pending entry; publish_preview consumes it and links |
publish_preview first → open_source second |
publish_preview records pending entry (needs publisher_code_slug arg); open_source consumes it and links |
Manual repair (rare)
If a pairing was wired wrong (e.g. after a rename), use:
link_to_listing(listing_slug="2004-my-app-pub", code_slug="my-app")
Architecture
community.iamstarchild.com (single gateway domain)
│
┌─────────────────┼─────────────────────┐
│ │ │
┌────────▼─────────┐ ┌───▼────────────┐ ┌─────▼──────────┐
│ /api/register │ │/api/code- │ │ /api/services │
│ /api/unregister │ │ projects/* │ │ /api/projects- │
│ /api/list │ │ (GitHub-backed)│ │ query/* │
└────────┬─────────┘ └───┬────────────┘ └─────┬──────────┘
│ │ │
┌────────▼─────────┐ ┌───▼────────────┐ ┌─────▼──────────┐
│ DB: route table │ │ GitHub: │ │ DB: │
│ + project_ │ │ community- │ │ service_ │
│ listings │ │ projects repo │ │ listings │
└──────────────────┘ └────────────────┘ │ (paid services)│
publish_preview() open_source() └────────────────┘
list_in_dashboard()
create_paid_service()
PUBLISH: publish_preview() — public URL
publish_preview(preview_id, slug="", title="", publisher_code_slug="")
Map a running service to https://community.iamstarchild.com/{user_id}-{slug}.
preview_id: from preview(action='serve'). Must be status=running.
slug: URL suffix only (lowercase alphanumeric + hyphens, 3-50 chars). User_id prefix is added automatically.
title: display name for the listing.
publisher_code_slug: optional cross-link binding to a code project's slug.
Returns {"ok": True, "url": "...", "publisher": {...}, "hint": "...", "x402_detected": bool} — plus a next_step warning when x402_detected
is true (complete the paid-listing chain).
Constraints:
publish_preview does NOT create a paid listing. If the endpoint
charges via x402 (returns 402), the publish flow is INCOMPLETE until you
also run create_paid_service → submit_for_review (recommended) → publish_service
— otherwise the marketplace shows nothing or "free". The return value
flags this (x402_detected: true + next_step) when billing is detected.
- Max 20 published previews per user (gateway returns 429 over).
- Service must be running. Stops working when the container goes down.
- Only works inside the Starchild Fly container (needs
FLY_MACHINE_ID).
- Listing visibility default is
is_public=false. A successful publish_preview allocates the URL but does NOT make it discoverable. Discovery requires a separate list_in_dashboard() call.
Companions:
unpublish_preview(slug) — stop the preview container service. URL becomes inaccessible (404). Does NOT affect listing state (is_public/review_status unchanged).
list_published_previews() — all currently published preview URLs for this user.
PUBLISH: open_source() — push code to GitHub
open_source(project_dir, version_bump="patch", message="")
Push project source to community-projects/projects/{user_id}/{slug}/ on GitHub.
project_dir: e.g. output/projects/my-task
version_bump: patch | minor | major | none
message: commit message body describing what this version changed.
You (the agent) should always compose this based on the actual code
changes you made in this session — never leave it blank if you know
what changed. Aim for one to three short lines describing the user-visible
change.
This is a PUBLISH action only — it does NOT list anything on the marketplace.
To make a project discoverable, call list_in_dashboard() (free) or
create_paid_service() (paid) separately after publishing.
Companions:
fork(source, dest_dir=None) — install someone else's open-sourced project locally
list_open_source(type=None, tag=None, user=None, q=None) — browse the GitHub catalog
get_open_source(source) — fetch one project's full metadata
remove_open_source(slug) — delete project directory from GitHub catalog (owner only)
validate_open_source(project_dir) — pre-flight check before publishing
Project structure
Every project under output/projects/{slug}/:
project.yaml # metadata (name, version, type, env_required, sc_proxy, publisher)
PROJECT.md # required sections: What / Required env / How to start / Outputs / Troubleshooting
.env.example # all env vars with placeholder values
.gitignore # secrets blacklist
src/
├── run.py # for type=task (must start: # -*- task-system: v3 -*-)
├── index.html # for type=service (or app.py + frontend)
└── main.py # for type=script
LIST (FREE): list_in_dashboard() — show on /projects gallery
list_in_dashboard(slug, name=None, description="", cover_url=None, tags=None)
Make a published preview discoverable in the public gallery at https://community.iamstarchild.com/projects. Without this, the preview URL works but is invisible to anyone who doesn't already know it.
slug: the full slug returned by publish_preview() (i.e. {user_id}-{suffix}).
name: gallery card display name. Defaults to slug.
description: ≤500 chars.
cover_url: must be on storage.googleapis.com, image.thum.io, or api.microlink.io. To upload a user-provided image, call upload_cover_image(slug, file_path) first — it handles presign → GCS upload → returns the public URL. See Cover Image Upload below.
tags: ≤5 tags, ≤20 chars each.
Returns {"ok": True, "listing": {...}, "url": "...", "dashboard_url": "..."}.
Constraints:
- Requires
publish_preview() to have run first for the same slug — returns 404 otherwise.
- Idempotent: calling again with different name/tags updates the existing listing.
- No review, no pricing — this is the free listing flow.
Companions:
unlist_from_dashboard(slug) — soft-unlist from gallery (sets is_public=false, review_status='unlisted', preserves view/favorite counts). URL stays alive. To re-list, call list_in_dashboard() again.
delete_listing(slug) — permanently delete the listing row AND the community_slugs record (removes view/favorite counts). URL becomes inaccessible (404). Removes from both explore and my-projects. Use unlist_from_dashboard() to hide without deleting.
get_listing_status(slug) — read-only check: returns {ok, exists, is_public, listing}.
LIST (PAID): Paid service listing on the Service Marketplace
Paid services charge for access via x402 (on-chain USDC/USDG settlement on the platform's enabled networks — by default Base + Monad + Robinhood + X Layer + Solana, following the all mode). An automated 6-check review is required before publishing — the service must pass all checks (approved) before publish_service() will work. API call examples are optional but recommended.
Multi-chain payment networks (plans-280)
Every paid service has a networks_mode that decides which chains buyers can pay on:
networks_mode |
Behavior |
When to use |
"all" (default) |
Accept payment on all platform mainnets (currently Base + Monad + Robinhood + X Layer + Solana; new chains are picked up automatically with no code change). The gateway stores supported_networks as NULL and expands it at read time. |
The common case — pass nothing or networks_mode="all". |
"custom" |
Accept payment only on the chains listed in supported_networks (a non-empty list of CAIP-2 ids, e.g. ["eip155:8453"]). Does NOT follow platform expansion. |
The user explicitly says "only Base" / "only Monad" / a specific subset. |
Rules:
- Default is
all. Never hard-code a single chain like ['eip155:8453'] as the default — that re-introduces the old Base-only behavior.
custom requires a non-empty supported_networks; an empty list is rejected.
provider_wallet is an EVM address used on every enabled chain (the Starchild facilitator settles to the same address on each chain). It is NOT Base-only.
- Buyers see the 402
accepts array (one entry per enabled chain, same price) and pick one chain per payment — this is standard x402 multi-accepts, not a protocol change.
- Gas for settlement is paid by the platform (Starchild facilitator), not the provider.
- To switch an existing service back to
all: update_service(service_id, networks_mode="all").
- To restrict to a subset:
update_service(service_id, networks_mode="custom", supported_networks=["eip155:8453"]).
This aligns with the x402 skill's monetize default (all). The two skills are on the same release train — if the gateway 402 accepts and the marketplace listing show different chains, one side was configured custom while the other stayed all.
Service lifecycle & review states (review is ADVISORY)
create ──▶ published ──▶ submit_for_review ─▶ pending ─▶ approved / rejected
│ (required before publishing — must pass to go live)
│ │ fix via update_service(), re-check
▼ ▼
publish_service() ─────────────────▶ listed ◀─▶ unlisted (owner takedown / re-list)
│
▼
unavailable ──▶ restore ──▶ listed
Review is a self-check, not a gate: submit_for_review() runs 5 automated
checks (api_reachable, pricing_consistency, x402_payment, response_match,
doc_completeness, examples_provided) and stores a report for the owner.
publish_service() requires the service to be in approved state (or unlisted
for re-listing). The review must pass before publishing — run
submit_for_review() first so a
broken endpoint is caught before buyers can pay for it. A rejected report does NOT block listing; a check run against an
already-listed service never delists it.
⚡ Scenario Selection Decision Tree — MUST follow before creating any paid service
Step 1: Does the service have a Starchild project page (published via publish_preview())?
- YES, and the page is free to browse → Flow D. Use
service_type="paid_project" + project_slug. The free page is published via publish_preview(), and the paid API sits behind x402 on /api/* routes. The upstream app serves the free intro page at / and the paid API at /api/*.
- YES, but the entire page requires payment → Flow B (Form 1). Use
service_type="paid_project" + project_slug. The user implements their own access control (paywall + credential validation). See the x402 skill's "Paid Project: two forms" section.
- NO (standalone API, no project page) → Flow C or E. Use
service_type="paid_api" WITHOUT project_slug. Do NOT create an index.html or publish a preview — there is no free page. The public URL root will show the x402 402 challenge or gateway info.
Step 2: Does the user want multiple API endpoints at different prices?
- YES → Use
api_endpoints array in ONE create_paid_service() call (Flow E). Do NOT create multiple separate services.
- NO → Single endpoint, use
api_endpoint only.
Step 3: Combine the answers:
| User wants |
Free page? |
Multi-endpoint? |
Flow |
service_type |
project_slug |
api_endpoints |
| Paid subscription project (entire site behind paywall) |
YES |
NO |
B |
paid_project |
required |
— |
| Standalone paid API (no webpage) |
NO |
NO |
C |
paid_api |
omit |
— |
| Free intro page + paid API |
YES |
NO |
D |
paid_project |
required |
— |
| Free intro page + multiple paid APIs |
YES |
YES |
D+E |
paid_project |
required |
required |
| Multiple paid APIs (no webpage) |
NO |
YES |
E |
paid_api |
omit |
required |
⚠️ Common Flow confusion mistakes (from real incidents)
| Mistake |
What goes wrong |
Correct action |
User says "write an intro page AND a paid API" but agent uses paid_api + creates a separate project preview |
Service and project are disconnected — marketplace shows two items, one free (blank) and one paid |
Use paid_project + project_slug (Flow D). The intro page and API are ONE service. |
| User says "pure paid API" but agent creates an index.html and publishes a preview |
Unnecessary free project page clutters the marketplace; the intro page may show blank/JSON |
Do NOT create index.html or publish_preview. Use paid_api (Flow C). The x402 gateway's 402 response IS the API's self-description. |
| User says "multiple API endpoints" but agent creates N separate services |
N marketplace cards instead of 1; port conflicts; upstream confusion |
Create ONE service with api_endpoints array (Flow E). |
| Agent reuses an upstream port already taken by another service |
Gateway proxies to the WRONG upstream — responses are from a different service |
Each service MUST have a unique upstream port. Check .x402/services.json for conflicts. |
Agent creates start.py with /docs route that conflicts with upstream's /docs |
Flask AssertionError: View function mapping is overwriting an existing endpoint |
Do NOT define /, /docs, or /index.html routes in both start.py and the upstream app — define them in only one place. |
Key rules:
- Do NOT pass
project_slug for standalone paid APIs. project_slug belongs to paid_project only — including the "free webpage + paid API" pattern (Flow D, which uses paid_project). Passing a preview slug or a non-existent slug for a standalone paid_api creates a phantom association — the backend will silently clear it, but you should not have passed it in the first place.
- Routing rule: service tied to a project page →
paid_project; paid_api is ONLY for standalone APIs with no project page. If your API has a published Starchild project (landing page/dashboard) that users can browse for free, use service_type="paid_project" + project_slug — this merges the service into the project card in the marketplace. If there is NO free project page, use paid_api and do NOT set project_slug. Passing paid_api + project_slug is auto-upgraded to paid_project by create_paid_service() (with a project_slug_warning in the response) — the final listing is always paid_project.
project_slug must be the full published slug WITH user prefix (e.g. 33-my-app), and must correspond to an existing row in project_listings (i.e. publish_preview() + list_in_dashboard() must have been called first).
api_endpoints is for services with multiple endpoints at different prices; each endpoint has its own path, price, and optional label.
- A project with
project_slug set will NOT appear in the "Free" tab — it moves to "All" and "Paid" tabs.
- Merged-into-project-card visibility: when a listed service has
project_slug pointing to a PUBLIC project, it is folded into that project's card in unified marketplace views. Consequence: the service will NOT appear as a standalone item in explore_services() or list_my_services() — this is by design, not a listing failure. It is still live and purchasable via the project card, get_service(service_id), and get_user_services(user_id), and it IS discoverable via explore_marketplace() (unified feed). To verify a merged service is listed, check get_service() → review_status == "listed", not explore_services() results.
- When the user asks for multiple APIs, create ONE service with
api_endpoints — do NOT create multiple separate services. See Flow E.
Tagging — predefined tag slugs for marketplace filtering
When creating a paid service, pass tags with 1-3 tag slugs from the predefined list below. The agent should choose the most relevant tags based on the service's name and description. Tags are used for marketplace filtering and discovery — they replace the old category field.
Predefined tag slugs (pick 1-3 most relevant):
| Domain |
Tags |
| DeFi & Trading |
defi, trading, dex, dex-swap, lending, lending-yield, yield, staking, derivatives, bridge |
| On-chain Data |
onchain-data, token-analytics, price-feed, wallet, wallet-portfolio, nft |
| AI & ML |
ai-inference, llm-inference, text-analysis, image-generation, text-to-speech, video-transcription, translation |
| Web & Data |
web-search, web-scraping, screenshot-pdf, news-feed, seo, data-service, data-storage, analytics |
| Security & Compliance |
aml-sanctions, security, privacy, threat-detection, agent-safety, agent-trust |
| Infrastructure |
smart-contract, oracle, zk-proofs, layer2, mev, compute, storage, developer-tools, identity, payment, payments |
| Social & Media |
social, social-media, gaming, metaverse |
| Finance (TradFi) |
stock-equity, sec-edgar, real-estate, insurance, prediction-market |
| Other |
dao, governance, email-sms, weather, geolocation, healthcare, agriculture, astrology-fortune, rwa, research-academic, legal-gov, launchpad |
Example: a DeFi price API → tags=["defi", "price-feed", "trading"]
Flow B — Paid Project listing
A paid project charges for access. There are two forms — both use
service_type="paid_project" + project_slug:
Form 1: Entire page behind paywall — the page itself requires payment.
The user implements their own access control (a login-like component with
credential validation). The platform provides the x402 payment protocol;
the user implements the paywall UI and credential logic. See the x402
skill's "Paid Project: two forms" section for implementation details and
the "How to pay with Agent" documentation template.
Form 2: Free page + paid API — the page is free to browse, API calls
cost money. This is Flow D (below). The upstream app serves the free intro
page at / and the paid API at /api/*.
Both forms are the same pattern — the only difference is what the user
implements (paywall interceptor for Form 1, nothing extra for Form 2).
- Have a running project with a public URL (via
publish_preview()).
- Configure x402 charging on the project's access endpoint using the x402 skill.
The endpoint must return
402 Payment Required when unpaid, and 200 + data after payment.
- Create the service record:
create_paid_service(
name="Premium Trading Signals",
description="Real-time trading signals with on-chain confirmation.",
service_type="paid_project",
tags=["trading", "onchain-data"],
project_slug="33-premium-signals", # FULL published slug WITH user prefix (the URL path segment)
api_endpoint="https://community.iamstarchild.com/33-premium-signals",
provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
pricing_model="monthly",
price=10,
service_description="Subscribers get a dashboard with live trading signals.",
)
Required paid-project fields: name, description, service_type,
project_slug, api_endpoint, provider_wallet, pricing_model, price,
service_description. Recommended: tags (1-3 predefined tag slugs for marketplace filtering).
⚠️ project_slug must be the full published slug including the user prefix
(e.g. 33-premium-signals, exactly the path segment in the project URL
https://community.iamstarchild.com/<slug>/). The gateway derives the API
endpoint as publicUrl + "/" + project_slug when api_endpoint is not set,
so an unprefixed or wrong slug breaks endpoint derivation and the
project↔service association. Fix an existing record with
update_service(service_id, project_slug="<full-slug>") — no re-listing needed.
- Required: run the automated review — paid services must pass review
before they can be published. A broken endpoint listed on the marketplace
can take buyers' money before you notice:
submit_for_review(service_id) # kicks off 6 automated checks asynchronously
get_review_status(service_id) # poll until no longer pending, then show the
# report to the user — THEY decide what to fix
A rejected report blocks publishing. Read review_feedback +
latest_task.checks, fix with update_service(), and
re-run submit_for_review() until approved.
- Publish once the review passes (approved):
publish_service(service_id)
The check can also be run again later against a listed service — it never
delists it.
Flow C — Paid API listing
A paid API is an external API service that already implements x402 charging.
⚠️ Do NOT pass project_slug for standalone paid APIs.
project_slug is ONLY for paid_project (required) or the "free webpage + paid API"
pattern (Flow D, where a published Starchild project page exists). For a standalone
paid_api with no associated free project page, omit project_slug entirely.
The backend validates project_slug against project_listings and silently clears
non-existent slugs, but you should not pass it in the first place.
⚠️ Choose paid_project if the API belongs to a published Starchild project.
If your API has a landing page / dashboard published via publish_preview() (i.e. it
exists as a project on community.iamstarchild.com), use service_type="paid_project"
project_slug=<full published slug WITH user prefix> (Flow B) — NOT paid_api. The project_slug is what
links the service to the project card (pricing badge, cross-navigation). A paid_api
listing has no project association, so the project card will keep showing "Free".
Use paid_api only for truly external/standalone APIs with no Starchild project.
Forgot the link? update the service record with project_slug — no need to re-list.
Have an x402-enabled API — the endpoint must return 402 when unpaid and 200 + data
after a valid X-PAYMENT header. Use the x402 skill to implement this if needed.
Ensuring purchases are recorded by Starchild
For the Starchild marketplace to track purchases, earnings, and usage stats,
choose one of the two approaches below based on your facilitator setup:
Option A — Use the Starchild facilitator (recommended)
Set your x402 middleware's facilitator URL to:
https://starchild-x402-facilitator.fly.dev
On successful settle, the Starchild facilitator automatically calls back
community-gateway to record the purchase. No extra setup needed — proceed
to step 2 with the default create_paid_service() call.
Option B — Use your own facilitator + proxy mode
If you use your own facilitator (or a third-party one), Starchild cannot
receive settlement callbacks. Instead, pass source="manual" when creating
the service record (step 2):
create_paid_service(
...,
source="manual", # ← enables proxy mode
)
This tells the marketplace to generate a proxy URL for your API:
https://community.iamstarchild.com/proxy/{service_id}/...
Users access your API through this proxy URL. The proxy transparently
forwards requests to your real api_endpoint and, on successful payment
(HTTP 200 with a payment-signature header), automatically records the
purchase in Starchild's database. You do NOT need to change your facilitator
URL or set up any callbacks.
402 response requirements (checked during review):
- The
402 response body must include a pricingModel field (platform format).
payTo must be your actual receiving EVM wallet address (used on every enabled chain).
- The
accepts array contains one entry per enabled chain (multi-accepts); buyers pick one chain per payment. Each entry has the same amount (USDC, 6 decimals) — the platform does not support per-chain pricing in this release.
- The response must be a valid x402 challenge that clients can parse.
Create the service record (service_type = "paid_api"):
create_paid_service(
name="On-chain Whale Tracker API",
description="REST API returning real-time whale wallet movements across 12 chains.",
service_type="paid_api",
tags=["onchain-data", "wallet-portfolio", "trading"],
api_endpoint="https://api.example.com/v1/whales",
provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
pricing_model="pay_per_use",
price=0.01,
free_trial_count=3,
api_documentation="# Whale Tracker API\n\n## GET /v1/whales\n\nReturns recent whale transactions.\n\n### Parameters\n| name | type | required | description |\n|---|---|---|---|\n| chain | string | no | Filter by chain id (default: all) |\n| limit | int | no | Max results (default: 50, max: 200) |\n\n### Response\n```json\n[{\"hash\":\"0x...\",\"from\":\"0x...\",\"to\":\"0x...\",\"value\":\"1000000\",\"token\":\"USDC\",\"chain\":\"base\",\"ts\":1700000000}]\n```",
example_request="curl https://api.example.com/v1/whales?chain=base&limit=10",
example_response='[{"hash":"0xabc...","from":"0x111...","to":"0x222...","value":"5000000","token":"USDC","chain":"base","ts":1700000000}]',
)
Required paid-API fields: name, description, service_type, api_endpoint,
provider_wallet, pricing_model, price, api_documentation.
Recommended (optional): example_request, example_response (improves buyer experience).
Optional: free_trial_count (only for pay_per_use),
source ("manual" for proxy mode — see step 1 Option B above; omit for default
Starchild facilitator mode),
cover_url (custom cover image URL — must be on storage.googleapis.com or other
allowed domains; if not provided, the agent should auto-generate a suitable cover
image based on the service name and description, upload it via the image upload
service, and pass the resulting URL).
Cover image for paid services
Paid services do NOT auto-generate a cover image (unlike free projects which get
auto-captured screenshots). Pass cover_url in create_paid_service() — must be on
storage.googleapis.com (or image.thum.io / api.microlink.io).
⚠️ MANDATORY: When the user provides an image or you need to set a cover, call
upload_cover_image(slug, file_path). This function handles the full flow:
presign URL → compress → upload to GCS → return storage.googleapis.com public URL.
Do NOT use imgur, data URIs, or any other hosting — the gateway validates the domain.
If the user does not provide an image, generate one (e.g. using an image generation
skill), save it locally, then call upload_cover_image().
You can also use update_service(cover_url=...) later to change the cover.
See Cover Image Upload for the complete reference.
- Run review → same as Flow B step 4 (required before publishing).
- Publish → same as Flow B step 5 (requires approved status).
Flow D — Free Webpage + Paid API (hybrid)
Your project has a free landing page (published via publish_preview()) AND a paid API
endpoint. Users can browse the project page for free, but API calls cost money.
The marketplace shows a single merged card with both "Visit Project" and "Call API" buttons.
- Publish the project via
publish_preview() — this creates the free landing page.
- Configure x402 charging on the API endpoint (e.g.
/api/random returns 402).
- Create the service record with
service_type="paid_project" + project_slug:
create_paid_service(
name="Random9 API",
description="Random 9-digit number API. Free docs page + paid API calls.",
service_type="paid_project",
tags=["developer-tools"],
project_slug="33-random9-api", # FULL slug WITH user prefix — links to the free project page
api_endpoint="https://community.iamstarchild.com/33-random9-api/api/random",
provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
pricing_model="pay_per_use",
price=0.01,
service_description="Paid access to the Random9 API endpoint; the docs page stays free.", # required for paid_project
api_documentation="# Random9 API\n## GET /api/random\nReturns a random 9-digit number.",
example_request="curl https://community.iamstarchild.com/33-random9-api/api/random",
example_response='{"random":"482917365","digits":9}',
)
The project_slug merges this service into the project card. The project page (/)
stays free; only the API endpoint (/api/random) requires payment.
Note: if service_type="paid_api" is passed together with project_slug,
create_paid_service() auto-upgrades it to paid_project and returns a
project_slug_warning — the stored listing is always paid_project. Passing
paid_project directly (as above) is the canonical form.
- Publish + optional self-check — same as Flow B steps 4–5.
Flow E — Multi-Endpoint API
Your service has multiple API endpoints at different prices (e.g. basic $0.01, premium $0.10).
Each endpoint is listed separately in the marketplace detail view.
⚠️ When the user asks for multiple APIs, create ONE service with api_endpoints — NOT multiple separate services.
For example, if the user says "develop three paid APIs and list them", do NOT call
create_paid_service() three times. Instead, create a single service with an
api_endpoints array containing all three endpoints. This gives users a unified
marketplace card where they can see and purchase individual endpoints.
Only create multiple services if the APIs are truly unrelated (different domains,
different audiences, different pricing models).
Configure x402 charging with per-route pricing:
# Default networks_mode is "all" (Base + Monad). Omit --networks to follow
# the platform mainnet set; pass --networks eip155:8453 only if the user
# explicitly wants to restrict to a single chain.
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
--mode pay_per_use --price 0.01 \
--route "GET /api/basic=$0.01" --route "GET /api/premium=$0.10" \
--route "POST /api/batch=$0.50" \
--facilitator $FAC
Create the service record with api_endpoints:
create_paid_service(
name="Data API Service",
description="Multiple API endpoints at different prices.",
service_type="paid_api",
tags=["data-service"],
api_endpoint="https://example.com/api/basic", # primary endpoint for review
api_endpoint
…(truncated)
1---
2name: community-publish
3version: 0.36.0
4description: |
5 Publish previews to a public URL, open-source projects to community GitHub, and list services (free or paid) on the Service Marketplace.
6
7 Use when the user wants to share, publish, list, open-source, or monetize what they built (e.g. make this dashboard public, share my project, push to GitHub, 上架到服务市场, 上架付费服务, 提交审核).
8delivery: script
9metadata:
10 source: https://skillmd.com/skills/starchild-ai-agent/community-publish
11 starchild:
12 emoji: 📦
13 skillKey: community-publish
14user-invocable: true
15disable-model-invocation: false
16
17---
18
19## Two concepts: PUBLISH vs LIST — never confuse them
20
21This skill handles two fundamentally different concepts. Mixing them up is the #1 source of wrong answers.
22
23| Concept | What it means | Functions |
24|---|---|---|
25| **PUBLISH (发布)** | Make something **accessible** — a URL works, or code is on GitHub | `publish_preview`, `unpublish_preview`, `list_published_previews`, `open_source`, `remove_open_source`, `list_open_source`, `get_open_source`, `fork`, `validate_open_source` |
26| **LIST (上架)** | Make something **discoverable/purchasable** on the marketplace | Free: `list_in_dashboard`, `unlist_from_dashboard`, `delete_listing`, `get_listing_status`<br>Paid: `create_paid_service`, `submit_for_review`, `get_review_status`, `publish_service`, `unpublish_service`, `list_my_services`, `get_service`, `update_service`, `delete_service`, `restore_service`<br>Cover: `upload_cover_image`<br>Browse + consumer: `explore_services`, `get_service_detail`, `get_service_pricing`, `get_service_reviews`, `write_service_review`, `favorite_service`, `unfavorite_service`, `get_favorite_services`, `get_user_services`, `get_service_earnings`, `get_earnings_summary`, `get_service_tags`, `get_featured_services`<br>Projects query: `explore_projects`, `my_projects`, `favorite_projects`, `get_tab_counts`, `get_popular_tags`, `get_user_projects`, `favorite_project`, `unfavorite_project` |
27
28**Publishing does NOT auto-list.** `publish_preview()` only allocates the URL. `open_source()` only pushes code. Neither makes the project discoverable on the marketplace — that requires a separate, deliberate LIST call.
29
30### Listing has two flows
31
32| Flow | When to use | Review? | Pricing? | Functions |
33|---|---|---|---|---|
34| **Free listing** | Free project, show on `/projects` gallery | No | No | `list_in_dashboard()` |
35| **Paid listing** | Charge for access via x402 | Required (6-check review, must pass before publishing) | Yes (USDC/USDG/USDC(Solana) on platform networks — default Base+Monad+Robinhood+X Layer+Solana, follows `all`) | `create_paid_service()` → `submit_for_review()` (required) → `publish_service()` |
36
37> **`POST /api/services` no longer accepts `service_type: "free_project"`.** Free listing is done by `list_in_dashboard()` (the project gallery flow). Paid listing uses `create_paid_service()` + review + publish (the service API flow).
38
39### Limited-time free promo ≠ this skill
40
41After a **paid** service is listed, the owner may run a **time-window free promotion**
42(`free_promo_start` / `free_promo_end`). That is **not** marketplace listing work and is
43**not** implemented here.
44
45| Concept | What it is | Where |
46|---------|------------|--------|
47| Free **listing** | Free project on `/projects` gallery | this skill → `list_in_dashboard()` |
48| `free_trial_count` | N free calls before charge (pay_per_use only) | this skill → `create_paid_service(..., free_trial_count=N)` |
49| **Limited-time free promo** | Calendar window: amount-0 verify, no settle/debit | **x402 skill** → `skills/x402/references/selling.md` section **Limited-time free promotion** |
50
51If the user asks to “开限时免费 / free promo / free for N days” on an already-paid listing:
52read the **x402** skill (self-check P1–P5, then PUT free-promo). Do **not** invent APIs in
53community-publish or confuse it with `free_trial_count`.
54
55---
56
57## Visibility model — read this before answering "can others see it?"
58
59A project's "publicness" is **three orthogonal switches**, not one:
60
61| Switch | Off state | On state | Flipped by |
62|---|---|---|---|
63| **URL access** | Visiting the URL returns 404 | URL works for anyone who has the link | `publish_preview` / `unpublish_preview` |
64| **Gallery discoverability** | Not on `/projects` gallery | Appears in the gallery | `list_in_dashboard` / `unlist_from_dashboard` |
65| **Marketplace listing** | Not on the Service Marketplace | Discoverable + purchasable | `create_paid_service` + `publish_service` / `unpublish_service` |
66
67A project can be in any combination. Never collapse these into "is it public yet".
68
69**Status questions are read-only operations.** Whenever the user asks:
70- "is it visible / public / discoverable yet?"
71- "上架了吗 / 在 dashboard 上吗 / 别人能看到吗"
72- "is the listing live?"
73
74The authoritative answer comes ONLY from a fresh `get_listing_status(slug)` (free) or `get_review_status(service_id)` (paid) call. Do NOT infer from past actions.
75
76---
77
78## Project types — three only
79
80| type | What it is | Eligible for `publish_preview()`? |
81|---|---|---|
82| `task` | Scheduled cron/interval job | No (no HTTP port) |
83| `service` | Long-running HTTP service (dashboard, API, page) | **Yes** |
84| `script` | One-shot script | No (no HTTP port) |
85
86---
87
88## Routing — match user intent to the right action
89
90### A. Status intents — user wants to know current state
91
92| Sample phrasing | Action |
93|---|---|
94| "is it visible / public / discoverable / live?" | `get_listing_status(slug)` |
95| "上架了吗 / 在 dashboard 上吗 / 别人能不能看到" | `get_listing_status(slug)` |
96| "what URLs do I have published?" / "我发布了哪些" | `list_published_previews()` |
97| "what's open-sourced?" / "都有哪些开源代码" | `list_open_source(...)` |
98| "我的服务" / "my services" / "我的付费服务" | `list_my_services()` |
99| "审核状态" / "审核通过了吗" / "review status" | `get_review_status(service_id)` |
100
101### B. Action intents — user wants to change state
102
103| Sample phrasing | Action | Notes |
104|---|---|---|
105| "publish" / "share" / "make public" / "公开" / "发布" (no qualifier) | `publish_preview(preview_id)` | Allocates the URL only. Listing is NOT auto-flipped. |
106| "list on the dashboard" / "上架" / "show on community" / "make discoverable" / "发到广场" | `list_in_dashboard(slug)` | Free listing. Requires the preview to already exist. |
107| "上架付费服务" / "make this a paid service" / "上架到服务市场(付费)" | `create_paid_service(...)` → `submit_for_review()` (recommended) → `publish_service()` | Paid listing. Needs x402 config first. |
108| "publish AND list" / "发布并上架" | `publish_preview()` THEN `list_in_dashboard()` | Two separate calls in order. |
109| "remove from dashboard" / "下架" / "unlist" / "hide from gallery" | `unlist_from_dashboard(slug)` | Free listing only. Soft-unlist (sets `is_public=false`, `review_status='unlisted'`, preserves stats). Preview URL stays alive. |
110| "下架付费服务" / "unpublish service" | `unpublish_service(service_id)` | Paid listing only. |
111| "open source" / "open-source the code" / "开源代码" | `open_source(project_dir)` | Pushes code to GitHub. Does NOT list. |
112| "unpublish the URL" / "take down the link" / "停止服务" | `unpublish_preview(slug)` | Stops the preview container service only. Does NOT affect listing state (`is_public`/`review_status` unchanged). URL becomes inaccessible (404). |
113| "remove the open source" / "delete from GitHub" | `remove_open_source(slug)` | |
114| "fork" / "install someone's project" | `fork(source)` | |
115| "提交审核" / "submit for review" | `submit_for_review(service_id)` | Paid only. Required — must pass before publishing |
116| "发布服务" / "publish my service" | `publish_service(service_id)` | Paid only, requires approved or unlisted state |
117| "更新服务" / "update service" | `update_service(service_id, ...)` | Paid only |
118| "删除服务" / "delete service" | `delete_service(service_id)` | Paid only |
119| "删除项目" / "delete listing" / "permanently remove from marketplace" | `delete_listing(slug)` | Free listing only. Permanently deletes the listing row AND the `community_slugs` record. URL becomes inaccessible (404). Removes from both explore and my-projects. Use `unlist_from_dashboard()` to hide without deleting. |
120| Ambiguous after rereading | Ask one question | "你是要 (a) 发布公开 URL,(b) 免费上架到广场,(c) 付费上架到服务市场,还是 (d) 开源代码?" |
121
122---
123
124## Cross-link via `publisher:` binding
125
126When the same project has BOTH a public URL AND open-sourced code, you want them paired so the frontend renders "View Source" on the listing card and "Visit Live Demo" on the code card. This skill drives that pairing through one explicit binding in project.yaml.
127
128### How to declare the binding
129
130Add a `publisher:` block to `project.yaml`:
131
132```yaml
133name: my-app
134type: service
135version: 1.0.0
136publisher:
137 code_slug: my-app # OPTIONAL — defaults to manifest.name
138 public_slug: my-app-pub # OPTIONAL — URL suffix; defaults to code_slug
139```
140
141Both fields are optional. If omitted, both default to `manifest.name`.
142
143### Either side can be published first
144
145The gateway holds a pending entry until the second side arrives. **No ordering requirement**, no manual link step.
146
147| Order | What happens |
148|---|---|
149| `open_source` first → `publish_preview` second | open_source records pending entry; publish_preview consumes it and links |
150| `publish_preview` first → `open_source` second | publish_preview records pending entry (needs `publisher_code_slug` arg); open_source consumes it and links |
151
152### Manual repair (rare)
153
154If a pairing was wired wrong (e.g. after a rename), use:
155
156```python
157link_to_listing(listing_slug="2004-my-app-pub", code_slug="my-app")
158```
159
160---
161
162## Architecture
163
164```
165 community.iamstarchild.com (single gateway domain)
166 │
167 ┌─────────────────┼─────────────────────┐
168 │ │ │
169 ┌────────▼─────────┐ ┌───▼────────────┐ ┌─────▼──────────┐
170 │ /api/register │ │/api/code- │ │ /api/services │
171 │ /api/unregister │ │ projects/* │ │ /api/projects- │
172 │ /api/list │ │ (GitHub-backed)│ │ query/* │
173 └────────┬─────────┘ └───┬────────────┘ └─────┬──────────┘
174 │ │ │
175 ┌────────▼─────────┐ ┌───▼────────────┐ ┌─────▼──────────┐
176 │ DB: route table │ │ GitHub: │ │ DB: │
177 │ + project_ │ │ community- │ │ service_ │
178 │ listings │ │ projects repo │ │ listings │
179 └──────────────────┘ └────────────────┘ │ (paid services)│
180 publish_preview() open_source() └────────────────┘
181 list_in_dashboard()
182 create_paid_service()
183```
184
185---
186
187## PUBLISH: `publish_preview()` — public URL
188
189`publish_preview(preview_id, slug="", title="", publisher_code_slug="")`
190
191Map a running service to `https://community.iamstarchild.com/{user_id}-{slug}`.
192
193- `preview_id`: from `preview(action='serve')`. Must be `status=running`.
194- `slug`: URL suffix only (lowercase alphanumeric + hyphens, 3-50 chars). User_id prefix is added automatically.
195- `title`: display name for the listing.
196- `publisher_code_slug`: optional cross-link binding to a code project's slug.
197
198Returns `{"ok": True, "url": "...", "publisher": {...}, "hint": "...",
199"x402_detected": bool}` — plus a `next_step` warning when `x402_detected`
200is true (complete the paid-listing chain).
201
202**Constraints:**
203- **`publish_preview` does NOT create a paid listing.** If the endpoint
204 charges via x402 (returns 402), the publish flow is INCOMPLETE until you
205 also run `create_paid_service` → `submit_for_review` (recommended) → `publish_service`
206 — otherwise the marketplace shows nothing or "free". The return value
207 flags this (`x402_detected: true` + `next_step`) when billing is detected.
208- Max 20 published previews per user (gateway returns 429 over).
209- Service must be running. Stops working when the container goes down.
210- Only works inside the Starchild Fly container (needs `FLY_MACHINE_ID`).
211- **Listing visibility default is `is_public=false`.** A successful `publish_preview` allocates the URL but does NOT make it discoverable. Discovery requires a separate `list_in_dashboard()` call.
212
213**Companions:**
214- `unpublish_preview(slug)` — stop the preview container service. URL becomes inaccessible (404). Does NOT affect listing state (`is_public`/`review_status` unchanged).
215- `list_published_previews()` — all currently published preview URLs for this user.
216
217---
218
219## PUBLISH: `open_source()` — push code to GitHub
220
221`open_source(project_dir, version_bump="patch", message="")`
222
223Push project source to `community-projects/projects/{user_id}/{slug}/` on GitHub.
224
225- `project_dir`: e.g. `output/projects/my-task`
226- `version_bump`: `patch` | `minor` | `major` | `none`
227- `message`: commit message body describing what this version changed.
228 **You (the agent) should always compose this** based on the actual code
229 changes you made in this session — never leave it blank if you know
230 what changed. Aim for one to three short lines describing the user-visible
231 change.
232
233**This is a PUBLISH action only — it does NOT list anything on the marketplace.**
234To make a project discoverable, call `list_in_dashboard()` (free) or
235`create_paid_service()` (paid) separately after publishing.
236
237**Companions:**
238- `fork(source, dest_dir=None)` — install someone else's open-sourced project locally
239- `list_open_source(type=None, tag=None, user=None, q=None)` — browse the GitHub catalog
240- `get_open_source(source)` — fetch one project's full metadata
241- `remove_open_source(slug)` — delete project directory from GitHub catalog (owner only)
242- `validate_open_source(project_dir)` — pre-flight check before publishing
243
244### Project structure
245
246Every project under `output/projects/{slug}/`:
247
248```
249project.yaml # metadata (name, version, type, env_required, sc_proxy, publisher)
250PROJECT.md # required sections: What / Required env / How to start / Outputs / Troubleshooting
251.env.example # all env vars with placeholder values
252.gitignore # secrets blacklist
253src/
254 ├── run.py # for type=task (must start: # -*- task-system: v3 -*-)
255 ├── index.html # for type=service (or app.py + frontend)
256 └── main.py # for type=script
257```
258
259---
260
261## LIST (FREE): `list_in_dashboard()` — show on /projects gallery
262
263`list_in_dashboard(slug, name=None, description="", cover_url=None, tags=None)`
264
265Make a published preview discoverable in the public gallery at `https://community.iamstarchild.com/projects`. Without this, the preview URL works but is invisible to anyone who doesn't already know it.
266
267- `slug`: the **full** slug returned by `publish_preview()` (i.e. `{user_id}-{suffix}`).
268- `name`: gallery card display name. Defaults to `slug`.
269- `description`: ≤500 chars.
270- `cover_url`: must be on `storage.googleapis.com`, `image.thum.io`, or `api.microlink.io`. **To upload a user-provided image, call `upload_cover_image(slug, file_path)` first** — it handles presign → GCS upload → returns the public URL. See [Cover Image Upload](#cover-image-upload-flow) below.
271- `tags`: ≤5 tags, ≤20 chars each.
272
273Returns `{"ok": True, "listing": {...}, "url": "...", "dashboard_url": "..."}`.
274
275**Constraints:**
276- Requires `publish_preview()` to have run first for the same slug — returns 404 otherwise.
277- Idempotent: calling again with different name/tags updates the existing listing.
278- No review, no pricing — this is the free listing flow.
279
280**Companions:**
281- `unlist_from_dashboard(slug)` — soft-unlist from gallery (sets `is_public=false`, `review_status='unlisted'`, preserves view/favorite counts). URL stays alive. To re-list, call `list_in_dashboard()` again.
282- `delete_listing(slug)` — permanently delete the listing row AND the `community_slugs` record (removes view/favorite counts). URL becomes inaccessible (404). Removes from both explore and my-projects. Use `unlist_from_dashboard()` to hide without deleting.
283- `get_listing_status(slug)` — read-only check: returns `{ok, exists, is_public, listing}`.
284
285---
286
287## LIST (PAID): Paid service listing on the Service Marketplace
288
289Paid services charge for access via x402 (on-chain USDC/USDG settlement on the platform's enabled networks — by default Base + Monad + Robinhood + X Layer + Solana, following the `all` mode). An automated 6-check review is required before publishing — the service must pass all checks (approved) before `publish_service()` will work. API call examples are optional but recommended.
290
291#### Multi-chain payment networks (plans-280)
292
293Every paid service has a **networks_mode** that decides which chains buyers can pay on:
294
295| `networks_mode` | Behavior | When to use |
296|---|---|---|
297| `"all"` (default) | Accept payment on **all platform mainnets** (currently Base + Monad + Robinhood + X Layer + Solana; new chains are picked up automatically with no code change). The gateway stores `supported_networks` as NULL and expands it at read time. | The common case — pass nothing or `networks_mode="all"`. |
298| `"custom"` | Accept payment **only** on the chains listed in `supported_networks` (a non-empty list of CAIP-2 ids, e.g. `["eip155:8453"]`). Does NOT follow platform expansion. | The user explicitly says "only Base" / "only Monad" / a specific subset. |
299
300**Rules:**
301- **Default is `all`.** Never hard-code a single chain like `['eip155:8453']` as the default — that re-introduces the old Base-only behavior.
302- `custom` requires a non-empty `supported_networks`; an empty list is rejected.
303- `provider_wallet` is an **EVM address used on every enabled chain** (the Starchild facilitator settles to the same address on each chain). It is NOT Base-only.
304- Buyers see the 402 `accepts` array (one entry per enabled chain, same price) and **pick one chain per payment** — this is standard x402 multi-accepts, not a protocol change.
305- Gas for settlement is paid by the platform (Starchild facilitator), not the provider.
306- To switch an existing service back to `all`: `update_service(service_id, networks_mode="all")`.
307- To restrict to a subset: `update_service(service_id, networks_mode="custom", supported_networks=["eip155:8453"])`.
308
309This aligns with the **x402 skill's `monetize`** default (`all`). The two skills are on the same release train — if the gateway 402 `accepts` and the marketplace listing show different chains, one side was configured `custom` while the other stayed `all`.
310
311### Service lifecycle & review states (review is ADVISORY)
312
313```
314 create ──▶ published ──▶ submit_for_review ─▶ pending ─▶ approved / rejected
315 │ (required before publishing — must pass to go live)
316 │ │ fix via update_service(), re-check
317 ▼ ▼
318 publish_service() ─────────────────▶ listed ◀─▶ unlisted (owner takedown / re-list)
319 │
320 ▼
321 unavailable ──▶ restore ──▶ listed
322```
323
324Review is a **self-check, not a gate**: `submit_for_review()` runs 5 automated
325checks (api_reachable, pricing_consistency, x402_payment, response_match,
326doc_completeness, examples_provided) and stores a report for the owner.
327`publish_service()` requires the service to be in `approved` state (or `unlisted`
328for re-listing). **The review must pass before publishing** — run
329`submit_for_review()` first so a
330broken endpoint is caught before buyers can pay for it. A `rejected` report does NOT block listing; a check run against an
331already-`listed` service never delists it.
332
333### ⚡ Scenario Selection Decision Tree — MUST follow before creating any paid service
334
335**Step 1: Does the service have a Starchild project page (published via `publish_preview()`)?**
336- **YES, and the page is free to browse** → Flow D. Use `service_type="paid_project"` + `project_slug`. The free page is published via `publish_preview()`, and the paid API sits behind x402 on `/api/*` routes. The upstream app serves the free intro page at `/` and the paid API at `/api/*`.
337- **YES, but the entire page requires payment** → Flow B (Form 1). Use `service_type="paid_project"` + `project_slug`. The user implements their own access control (paywall + credential validation). See the x402 skill's "Paid Project: two forms" section.
338- **NO (standalone API, no project page)** → Flow C or E. Use `service_type="paid_api"` WITHOUT `project_slug`. Do NOT create an index.html or publish a preview — there is no free page. The public URL root will show the x402 402 challenge or gateway info.
339
340**Step 2: Does the user want multiple API endpoints at different prices?**
341- **YES** → Use `api_endpoints` array in ONE `create_paid_service()` call (Flow E). Do NOT create multiple separate services.
342- **NO** → Single endpoint, use `api_endpoint` only.
343
344**Step 3: Combine the answers:**
345
346| User wants | Free page? | Multi-endpoint? | Flow | service_type | project_slug | api_endpoints |
347|------------|-----------|-----------------|------|-------------|--------------|---------------|
348| Paid subscription project (entire site behind paywall) | YES | NO | B | `paid_project` | required | — |
349| Standalone paid API (no webpage) | NO | NO | C | `paid_api` | **omit** | — |
350| Free intro page + paid API | YES | NO | D | `paid_project` | required | — |
351| Free intro page + multiple paid APIs | YES | YES | D+E | `paid_project` | required | required |
352| Multiple paid APIs (no webpage) | NO | YES | E | `paid_api` | **omit** | required |
353
354### ⚠️ Common Flow confusion mistakes (from real incidents)
355
356| Mistake | What goes wrong | Correct action |
357|---------|----------------|----------------|
358| User says "write an intro page AND a paid API" but agent uses `paid_api` + creates a separate project preview | Service and project are disconnected — marketplace shows two items, one free (blank) and one paid | Use `paid_project` + `project_slug` (Flow D). The intro page and API are ONE service. |
359| User says "pure paid API" but agent creates an index.html and publishes a preview | Unnecessary free project page clutters the marketplace; the intro page may show blank/JSON | Do NOT create index.html or publish_preview. Use `paid_api` (Flow C). The x402 gateway's 402 response IS the API's self-description. |
360| User says "multiple API endpoints" but agent creates N separate services | N marketplace cards instead of 1; port conflicts; upstream confusion | Create ONE service with `api_endpoints` array (Flow E). |
361| Agent reuses an upstream port already taken by another service | Gateway proxies to the WRONG upstream — responses are from a different service | Each service MUST have a unique upstream port. Check `.x402/services.json` for conflicts. |
362| Agent creates start.py with `/docs` route that conflicts with upstream's `/docs` | Flask `AssertionError: View function mapping is overwriting an existing endpoint` | Do NOT define `/`, `/docs`, or `/index.html` routes in both start.py and the upstream app — define them in only one place. |
363
364**Key rules:**
365- **Do NOT pass `project_slug` for standalone paid APIs.** `project_slug` belongs to `paid_project` only — including the "free webpage + paid API" pattern (Flow D, which uses `paid_project`). Passing a preview slug or a non-existent slug for a standalone `paid_api` creates a phantom association — the backend will silently clear it, but you should not have passed it in the first place.
366- **Routing rule: service tied to a project page → `paid_project`; `paid_api` is ONLY for standalone APIs with no project page.** If your API has a published Starchild project (landing page/dashboard) that users can browse for free, use `service_type="paid_project"` + `project_slug` — this merges the service into the project card in the marketplace. If there is NO free project page, use `paid_api` and do NOT set `project_slug`. Passing `paid_api` + `project_slug` is auto-upgraded to `paid_project` by `create_paid_service()` (with a `project_slug_warning` in the response) — the final listing is always `paid_project`.
367- `project_slug` must be the **full published slug WITH user prefix** (e.g. `33-my-app`), and must correspond to an existing row in `project_listings` (i.e. `publish_preview()` + `list_in_dashboard()` must have been called first).
368- `api_endpoints` is for services with multiple endpoints at different prices; each endpoint has its own `path`, `price`, and optional `label`.
369- A project with `project_slug` set will NOT appear in the "Free" tab — it moves to "All" and "Paid" tabs.
370- **Merged-into-project-card visibility:** when a listed service has `project_slug` pointing to a PUBLIC project, it is folded into that project's card in unified marketplace views. Consequence: the service will NOT appear as a standalone item in `explore_services()` or `list_my_services()` — this is by design, not a listing failure. It is still live and purchasable via the project card, `get_service(service_id)`, and `get_user_services(user_id)`, and it IS discoverable via `explore_marketplace()` (unified feed). To verify a merged service is listed, check `get_service()` → `review_status == "listed"`, not `explore_services()` results.
371- **When the user asks for multiple APIs, create ONE service with `api_endpoints`** — do NOT create multiple separate services. See Flow E.
372
373### Tagging — predefined tag slugs for marketplace filtering
374
375When creating a paid service, pass `tags` with 1-3 tag slugs from the predefined list below. The agent should choose the most relevant tags based on the service's name and description. Tags are used for marketplace filtering and discovery — they replace the old `category` field.
376
377**Predefined tag slugs** (pick 1-3 most relevant):
378
379| Domain | Tags |
380|--------|------|
381| DeFi & Trading | `defi`, `trading`, `dex`, `dex-swap`, `lending`, `lending-yield`, `yield`, `staking`, `derivatives`, `bridge` |
382| On-chain Data | `onchain-data`, `token-analytics`, `price-feed`, `wallet`, `wallet-portfolio`, `nft` |
383| AI & ML | `ai-inference`, `llm-inference`, `text-analysis`, `image-generation`, `text-to-speech`, `video-transcription`, `translation` |
384| Web & Data | `web-search`, `web-scraping`, `screenshot-pdf`, `news-feed`, `seo`, `data-service`, `data-storage`, `analytics` |
385| Security & Compliance | `aml-sanctions`, `security`, `privacy`, `threat-detection`, `agent-safety`, `agent-trust` |
386| Infrastructure | `smart-contract`, `oracle`, `zk-proofs`, `layer2`, `mev`, `compute`, `storage`, `developer-tools`, `identity`, `payment`, `payments` |
387| Social & Media | `social`, `social-media`, `gaming`, `metaverse` |
388| Finance (TradFi) | `stock-equity`, `sec-edgar`, `real-estate`, `insurance`, `prediction-market` |
389| Other | `dao`, `governance`, `email-sms`, `weather`, `geolocation`, `healthcare`, `agriculture`, `astrology-fortune`, `rwa`, `research-academic`, `legal-gov`, `launchpad` |
390
391Example: a DeFi price API → `tags=["defi", "price-feed", "trading"]`
392
393### Flow B — Paid Project listing
394
395A paid project charges for access. There are two forms — both use
396`service_type="paid_project"` + `project_slug`:
397
398**Form 1: Entire page behind paywall** — the page itself requires payment.
399The user implements their own access control (a login-like component with
400credential validation). The platform provides the x402 payment protocol;
401the user implements the paywall UI and credential logic. See the x402
402skill's "Paid Project: two forms" section for implementation details and
403the "How to pay with Agent" documentation template.
404
405**Form 2: Free page + paid API** — the page is free to browse, API calls
406cost money. This is Flow D (below). The upstream app serves the free intro
407page at `/` and the paid API at `/api/*`.
408
409Both forms are the same pattern — the only difference is what the user
410implements (paywall interceptor for Form 1, nothing extra for Form 2).
411
4121. **Have a running project** with a public URL (via `publish_preview()`).
4132. **Configure x402 charging** on the project's access endpoint using the **x402 skill**.
414 The endpoint must return `402 Payment Required` when unpaid, and `200` + data after payment.
4153. **Create the service record:**
416
417```python
418create_paid_service(
419 name="Premium Trading Signals",
420 description="Real-time trading signals with on-chain confirmation.",
421 service_type="paid_project",
422 tags=["trading", "onchain-data"],
423 project_slug="33-premium-signals", # FULL published slug WITH user prefix (the URL path segment)
424 api_endpoint="https://community.iamstarchild.com/33-premium-signals",
425 provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
426 pricing_model="monthly",
427 price=10,
428 service_description="Subscribers get a dashboard with live trading signals.",
429)
430```
431
432 Required paid-project fields: `name`, `description`, `service_type`,
433 `project_slug`, `api_endpoint`, `provider_wallet`, `pricing_model`, `price`,
434 `service_description`. Recommended: `tags` (1-3 predefined tag slugs for marketplace filtering).
435
436 ⚠️ `project_slug` must be the **full published slug including the user prefix**
437 (e.g. `33-premium-signals`, exactly the path segment in the project URL
438 `https://community.iamstarchild.com/<slug>/`). The gateway derives the API
439 endpoint as `publicUrl + "/" + project_slug` when `api_endpoint` is not set,
440 so an unprefixed or wrong slug breaks endpoint derivation and the
441 project↔service association. Fix an existing record with
442 `update_service(service_id, project_slug="<full-slug>")` — no re-listing needed.
443
4444. **Required: run the automated review** — paid services must pass review
445 before they can be published. A broken endpoint listed on the marketplace
446 can take buyers' money before you notice:
447
448```python
449submit_for_review(service_id) # kicks off 6 automated checks asynchronously
450get_review_status(service_id) # poll until no longer pending, then show the
451 # report to the user — THEY decide what to fix
452```
453
454 A `rejected` report blocks publishing. Read `review_feedback` +
455 `latest_task.checks`, fix with `update_service()`, and
456 re-run `submit_for_review()` until approved.
457
4585. **Publish** once the review passes (approved):
459
460```python
461publish_service(service_id)
462```
463
464 The check can also be run again later against a listed service — it never
465 delists it.
466
467### Flow C — Paid API listing
468
469A paid API is an external API service that already implements x402 charging.
470
471> **⚠️ Do NOT pass `project_slug` for standalone paid APIs.**
472> `project_slug` is ONLY for `paid_project` (required) or the "free webpage + paid API"
473> pattern (Flow D, where a published Starchild project page exists). For a standalone
474> `paid_api` with no associated free project page, omit `project_slug` entirely.
475> The backend validates `project_slug` against `project_listings` and silently clears
476> non-existent slugs, but you should not pass it in the first place.
477>
478> **⚠️ Choose `paid_project` if the API belongs to a published Starchild project.**
479> If your API has a landing page / dashboard published via `publish_preview()` (i.e. it
480> exists as a project on community.iamstarchild.com), use `service_type="paid_project"`
481> + `project_slug=<full published slug WITH user prefix>` (Flow B) — NOT `paid_api`. The `project_slug` is what
482> links the service to the project card (pricing badge, cross-navigation). A `paid_api`
483> listing has no project association, so the project card will keep showing "Free".
484> Use `paid_api` only for truly external/standalone APIs with no Starchild project.
485> Forgot the link? `update` the service record with `project_slug` — no need to re-list.
486
4871. **Have an x402-enabled API** — the endpoint must return `402` when unpaid and `200` + data
488 after a valid `X-PAYMENT` header. Use the **x402 skill** to implement this if needed.
489
490 #### Ensuring purchases are recorded by Starchild
491
492 For the Starchild marketplace to track purchases, earnings, and usage stats,
493 choose one of the two approaches below based on your facilitator setup:
494
495 **Option A — Use the Starchild facilitator (recommended)**
496
497 Set your x402 middleware's facilitator URL to:
498
499 ```
500 https://starchild-x402-facilitator.fly.dev
501 ```
502
503 On successful settle, the Starchild facilitator automatically calls back
504 community-gateway to record the purchase. No extra setup needed — proceed
505 to step 2 with the default `create_paid_service()` call.
506
507 **Option B — Use your own facilitator + proxy mode**
508
509 If you use your own facilitator (or a third-party one), Starchild cannot
510 receive settlement callbacks. Instead, pass `source="manual"` when creating
511 the service record (step 2):
512
513 ```python
514 create_paid_service(
515 ...,
516 source="manual", # ← enables proxy mode
517 )
518 ```
519
520 This tells the marketplace to generate a **proxy URL** for your API:
521
522 ```
523 https://community.iamstarchild.com/proxy/{service_id}/...
524 ```
525
526 Users access your API through this proxy URL. The proxy transparently
527 forwards requests to your real `api_endpoint` and, on successful payment
528 (HTTP 200 with a `payment-signature` header), automatically records the
529 purchase in Starchild's database. You do NOT need to change your facilitator
530 URL or set up any callbacks.
531
532 **402 response requirements** (checked during review):
533
534 - The `402` response body **must** include a `pricingModel` field (platform format).
535 - `payTo` **must** be your actual receiving EVM wallet address (used on every enabled chain).
536 - The `accepts` array contains one entry per enabled chain (multi-accepts); buyers pick one chain per payment. Each entry has the same `amount` (USDC, 6 decimals) — the platform does not support per-chain pricing in this release.
537 - The response must be a valid x402 challenge that clients can parse.
538
5392. **Create the service record** (`service_type = "paid_api"`):
540
541```python
542create_paid_service(
543 name="On-chain Whale Tracker API",
544 description="REST API returning real-time whale wallet movements across 12 chains.",
545 service_type="paid_api",
546 tags=["onchain-data", "wallet-portfolio", "trading"],
547 api_endpoint="https://api.example.com/v1/whales",
548 provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
549 pricing_model="pay_per_use",
550 price=0.01,
551 free_trial_count=3,
552 api_documentation="# Whale Tracker API\n\n## GET /v1/whales\n\nReturns recent whale transactions.\n\n### Parameters\n| name | type | required | description |\n|---|---|---|---|\n| chain | string | no | Filter by chain id (default: all) |\n| limit | int | no | Max results (default: 50, max: 200) |\n\n### Response\n```json\n[{\"hash\":\"0x...\",\"from\":\"0x...\",\"to\":\"0x...\",\"value\":\"1000000\",\"token\":\"USDC\",\"chain\":\"base\",\"ts\":1700000000}]\n```",
553 example_request="curl https://api.example.com/v1/whales?chain=base&limit=10",
554 example_response='[{"hash":"0xabc...","from":"0x111...","to":"0x222...","value":"5000000","token":"USDC","chain":"base","ts":1700000000}]',
555)
556```
557
558 Required paid-API fields: `name`, `description`, `service_type`, `api_endpoint`,
559 `provider_wallet`, `pricing_model`, `price`, `api_documentation`.
560 Recommended (optional): `example_request`, `example_response` (improves buyer experience).
561 Optional: `free_trial_count` (only for `pay_per_use`),
562 `source` (`"manual"` for proxy mode — see step 1 Option B above; omit for default
563 Starchild facilitator mode),
564 `cover_url` (custom cover image URL — must be on `storage.googleapis.com` or other
565 allowed domains; if not provided, the agent should auto-generate a suitable cover
566 image based on the service name and description, upload it via the image upload
567 service, and pass the resulting URL).
568
569 #### Cover image for paid services
570
571 Paid services do NOT auto-generate a cover image (unlike free projects which get
572 auto-captured screenshots). Pass `cover_url` in `create_paid_service()` — must be on
573 `storage.googleapis.com` (or `image.thum.io` / `api.microlink.io`).
574
575 **⚠️ MANDATORY: When the user provides an image or you need to set a cover, call
576 `upload_cover_image(slug, file_path)`.** This function handles the full flow:
577 presign URL → compress → upload to GCS → return `storage.googleapis.com` public URL.
578 Do NOT use imgur, data URIs, or any other hosting — the gateway validates the domain.
579
580 If the user does not provide an image, generate one (e.g. using an image generation
581 skill), save it locally, then call `upload_cover_image()`.
582
583 You can also use `update_service(cover_url=...)` later to change the cover.
584
585 See [Cover Image Upload](#cover-image-upload-flow) for the complete reference.
586
5873. **Run review** → same as Flow B step 4 (required before publishing).
5884. **Publish** → same as Flow B step 5 (requires approved status).
589
590### Flow D — Free Webpage + Paid API (hybrid)
591
592Your project has a free landing page (published via `publish_preview()`) AND a paid API
593endpoint. Users can browse the project page for free, but API calls cost money.
594The marketplace shows a single merged card with both "Visit Project" and "Call API" buttons.
595
5961. **Publish the project** via `publish_preview()` — this creates the free landing page.
5972. **Configure x402 charging** on the API endpoint (e.g. `/api/random` returns 402).
5983. **Create the service record** with `service_type="paid_project"` + `project_slug`:
599
600```python
601create_paid_service(
602 name="Random9 API",
603 description="Random 9-digit number API. Free docs page + paid API calls.",
604 service_type="paid_project",
605 tags=["developer-tools"],
606 project_slug="33-random9-api", # FULL slug WITH user prefix — links to the free project page
607 api_endpoint="https://community.iamstarchild.com/33-random9-api/api/random",
608 provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
609 pricing_model="pay_per_use",
610 price=0.01,
611 service_description="Paid access to the Random9 API endpoint; the docs page stays free.", # required for paid_project
612 api_documentation="# Random9 API\n## GET /api/random\nReturns a random 9-digit number.",
613 example_request="curl https://community.iamstarchild.com/33-random9-api/api/random",
614 example_response='{"random":"482917365","digits":9}',
615)
616```
617
618 The `project_slug` merges this service into the project card. The project page (`/`)
619 stays free; only the API endpoint (`/api/random`) requires payment.
620
621 > Note: if `service_type="paid_api"` is passed together with `project_slug`,
622 > `create_paid_service()` auto-upgrades it to `paid_project` and returns a
623 > `project_slug_warning` — the stored listing is always `paid_project`. Passing
624 > `paid_project` directly (as above) is the canonical form.
625
6264. **Publish + optional self-check** — same as Flow B steps 4–5.
627
628### Flow E — Multi-Endpoint API
629
630Your service has multiple API endpoints at different prices (e.g. basic $0.01, premium $0.10).
631Each endpoint is listed separately in the marketplace detail view.
632
633> **⚠️ When the user asks for multiple APIs, create ONE service with `api_endpoints` — NOT multiple separate services.**
634> For example, if the user says "develop three paid APIs and list them", do NOT call
635> `create_paid_service()` three times. Instead, create a single service with an
636> `api_endpoints` array containing all three endpoints. This gives users a unified
637> marketplace card where they can see and purchase individual endpoints.
638> Only create multiple services if the APIs are truly unrelated (different domains,
639> different audiences, different pricing models).
640
6411. **Configure x402 charging** with per-route pricing:
642 ```bash
643 # Default networks_mode is "all" (Base + Monad). Omit --networks to follow
644 # the platform mainnet set; pass --networks eip155:8453 only if the user
645 # explicitly wants to restrict to a single chain.
646 python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
647 --mode pay_per_use --price 0.01 \
648 --route "GET /api/basic=$0.01" --route "GET /api/premium=$0.10" \
649 --route "POST /api/batch=$0.50" \
650 --facilitator $FAC
651 ```
652
6532. **Create the service record** with `api_endpoints`:
654
655```python
656create_paid_service(
657 name="Data API Service",
658 description="Multiple API endpoints at different prices.",
659 service_type="paid_api",
660 tags=["data-service"],
661 api_endpoint="https://example.com/api/basic", # primary endpoint for review
662 api_endpoints=[
663 {"path": "GET /api/basic", "price": 0.01, "label": "Basic Query"},
664 {"path": "GET /api/premium", "price": 0.10, "label": "Premium Query"},
665 {"path": "POST /api/batch", "price": 0.50, "label": "Batch Process"},
666 ],
667 provider_wallet="0xAbC...yourEvmWallet", # EVM address for Base/Monad/Robinhood/X Layer; Solana address auto-fetched from Privy wallet
668 pricing_model="pay_per_use",
669 price=0.01, # price of the primary/default endpoint
670 api_documentation="# Data API\n## GET /api/basic\nBasic data.\n## GET /api/premium\nPremium analytics.",
671 example_request="curl https://example.com/api/basic",
672 example_response='{"data":"basic market info"}',
673)
674```
675
676 You can combine Flow D + Flow E: use `service_type="paid_project"` + `project_slug`
677 together with `api_endpoints` to link a free project page with multi-endpoint pricing.
678 The marketplace shows a merged project card with an endpoint list in the detail view.
679
6803. **Publish + optional self-check** — same as Flow B steps 4–5.
681
682### Review checks (6 automated checks — required for publishing)
683
684`submit_for_review()` runs these checks against the `api_endpoint`; the service must pass all checks to be approved for publishing. A check run against an already-listed service never delists it:
685
686| # | Check | What it verifies |
687|---|---|---|
688| 1 | `api_reachable` | The endpoint returns `402 Payment Required` when no `X-PAYMENT` header is sent |
689| 2 | `pricing_consistency` | The `amount` in the 402 response's `accepts` matches the `price` you declared (in USDC base units). With multi-chain `accepts` (one entry per enabled chain), each entry must carry the same `amount` — the platform does not support per-chain pricing in this release. |
690| 3 | `x402_payment` | After a valid x402 payment, the endpoint returns `200` + data |
691| 4 | `response_match` | The actual response's key fields match your `example_response` |
692| 5 | `doc_completeness` | `api_documentation` includes parameter descriptions, response format, and at least one example |
693
694 Check #5 is keyword-matched: the doc must contain a "Response" (or "响应格式")
695 section with actual body text under the heading — an empty section fails review.
696 `service_description` (paid_project) and `api_documentation` / `example_request` /
697 `example_response` (paid_api) are enforced at call time by `create_paid_service()`,
698 which errors before creating an unreviewable record.
699
700**Common rejection causes:**
701- 402 response `amount` doesn't match declared `price` (off by decimals / wrong unit).
702- Endpoint doesn't return 402 at all (x402 not wired up, or returns 200 to unauthenticated requests).
703- `example_response` doesn't match what the API actually returns after payment.
704- Documentation missing parameter table or response schema.
705
706### Pricing models
707
708All paid services use the x402 `exact` payment scheme (on-chain USDC/USDG settlement on the platform's enabled networks — by default Base + Monad + Robinhood + X Layer + Solana, following `networks_mode="all"`). Gas for settlement is paid by the Starchild facilitator, not the provider.
709
710| `pricing_model` | Meaning | x402 behavior | Typical use |
711|---|---|---|---|
712| `pay_per_use` | Per-call charge | Every request with valid `X-PAYMENT` → settle (charge) | API calls |
713| `lifetime` | One-time buyout | First payment settles; subsequent requests verify past settlement, no re-charge | One-time purchases |
714| `monthly` | Monthly subscription | Settles once per billing month; re-charge after expiry | Web subscriptions, API monthly plans |
715| `weekly` | Weekly subscription | Settles once per 7 days; re-charge after expiry | Short-term subscriptions |
716| `quarterly` | Quarterly subscription | Settles once per 90 days; re-charge after expiry | Quarterly plans |
717| `yearly` | Yearly subscription | Settles once per 365 days; re-charge after expiry | Annual plans (often discounted) |
718| `prepaid` | Prepaid balance | User deposits via `deposit-settle` (one on-chain tx), then each call debits balance off-chain (zero gas) | High-frequency micro-payments |
719
720> `free_trial_count` is only valid for `pay_per_use` — allows N free calls before charging.
721> It is **not** a calendar free promo. Time-window free (`free_promo_*`) → **x402** skill
722> (`selling.md` → Limited-time free promotion).
723
724#### Multi-plan (multiple pricing options)
725
726A service can offer multiple pricing plans simultaneously (e.g. weekly + monthly + yearly). Pass `pricing_options` array when creating the service:
727
728```python
729create_paid_service(
730 ...,
731 pricing_options=[
732 {"pricing_model": "weekly", "price": 3, "is_default": True, "label": "Weekly"},
733 {"pricing_model": "monthly", "price": 10, "label": "Monthly"},
734 {"pricing_model": "yearly", "price": 90, "label": "Yearly (Save 42%)"},
735 ],
736)
737```
738
739**Rules**:
740- `pay_per_use` cannot be combined with other pricing models.
741- Subscription models (weekly/monthly/quarterly/yearly) can be freely combined.
742- `lifetime` and `prepaid` can be combined with subscription models.
743- One option must be marked `is_default: True` (or the first is auto-marked).
744- The service's `pricing_model` and `price` fields are auto-synced to the default option.
745
746**Multi-plan 402 requirement**: The service's x402 middleware must support the `X-Pricing-Model` header — when a client sends `X-Pricing-Model: yearly`, the 402 response must return the yearly plan's price. Review verifies each plan's 402 amount individually.
747
748**Reference**: See `x402-facilitator/docs/pricing-models.md` for the full specification.
749
750#### Restricting payment to specific chains (custom networks)
751
752The default `networks_mode="all"` follows the platform mainnet set (Base + Monad + Robinhood + X Layer + Solana). Only restrict to a subset when the user explicitly asks for it ("only accept Base", "don't take Monad payments", etc.):
753
754```python
755# Create a service that ONLY accepts Base USDC (not Monad)
756create_paid_service(
757 ...,
758 networks_mode="custom",
759 supported_networks=["eip155:8453"], # CAIP-2 chain id; non-empty required
760)
761
762# Switch an existing service from all → custom (only Monad)
763update_service(service_id, networks_mode="custom", supported_networks=["eip155:143"])
764
765# Switch back to all (follow platform mainnets; clears the custom list)
766update_service(service_id, networks_mode="all")
767```
768
769**Do NOT default to `custom` + `['eip155:8453']`.** That re-introduces the old Base-only behavior. The default is `all`; only use `custom` when the user explicitly restricts.
770
771---
772
773### Service Examples (API call examples) — recommended but optional
774
775API call examples are **optional but strongly recommended**. They show
776buyers what the API returns — appearing as collapsible request/response
777pairs on the service detail page. Services without examples will still
778pass review, but the review report will note that examples are missing.
779
780**Recommended listing order:**
781
782```
7831. create_paid_service(...) → creates the service
7842. set_service_examples(service_id, examples) → recommended (improves buyer experience)
7853. submit_for_review(service_id) → required before publishing
7864. publish_service(service_id) → go live (requires approved)
787```
788
789**Adding examples:**
790
791```python
792set_service_examples("service-uuid", [
793 {
794 "title": "Query BTC Price",
795 "description": "Get current Bitcoin price in USD",
796 "request": 'curl -X GET "https://api.example.com/v1/price?symbol=BTC"',
797 "response": '{"symbol": "BTC", "price": 67234.56, "currency": "USD"}'
798 },
799 {
800 "title": "Query ETH Price",
801 "request": 'curl -X GET "https://api.example.com/v1/price?symbol=ETH"',
802 "response": '{"symbol": "ETH", "price": 3456.78, "currency": "USD"}'
803 }
804])
805```
806
807**Clearing examples** (rarely needed — `set_service_examples` replaces all):
808
809```python
810clear_service_examples("service-uuid")
811```
812
813**Best practices:**
814- Add 2-5 examples covering the most common use cases
815- Use descriptive titles that explain the scenario
816- Include realistic request parameters and response data
817- Show both simple and complex usage patterns
818- `set_service_examples()` replaces ALL examples — pass the complete list every time
819
820This supersedes the legacy single `example_request` / `example_response`
821fields passed in `create_paid_service()`. Services with legacy fields still
822pass the review (backward compatible), but new services should use
823`set_service_examples()` for richer multi-scenario demonstrations.
824
825### Paid service management functions
826
827| Function | Purpose |
828|---|---|
829| `create_paid_service(...)` | Create a service record (published state) |
830| `set_service_examples(service_id, examples)` | Set API call examples (optional, recommended) — replaces all examples |
831| `clear_service_examples(service_id)` | Remove all API call examples |
832| `submit_for_review(service_id)` | Run the 6-check automated review (required before publishing) |
833| `get_review_status(service_id)` | Poll review progress + per-check details |
834| `publish_service(service_id)` | Go live (requires approved or unlisted state) |
835| `unpublish_service(service_id)` | Take down (listed → unlisted) |
836| `list_my_services(cursor, limit)` | List your services (paginated) |
837| `get_service(service_id)` | Fetch one service by ID |
838| `update_service(service_id, **fields)` | Update service fields (e.g. fix after rejection) |
839| `delete_service(service_id)` | Permanently delete a service |
840| `restore_service(service_id)` | Restore an unavailable service back to listed |
841
842### Marketplace browse & consumer functions
843
844These functions let the agent browse the Service Marketplace, read reviews,
845write reviews, manage favorites, and check earnings — same as the web frontend.
846
847| Function | Purpose |
848|---|---|
849| `explore_marketplace(search, paid_only, ...)` | ⭐ **UNIFIED browse — use this FIRST to find paid services/APIs.** Project cards + standalone services in one feed (same as web All/Paid tabs); the only search path that surfaces services merged into public project cards. Items have `type`: `service` (use `id`) or `project` (paid cards carry `service_id`) — feed into `get_service_detail()` |
850| `explore_services(search, sort, tags, ...)` | Browse STANDALONE service items only (services API). ⚠️ Services merged into a public project card do NOT appear here — use `explore_marketplace()` for full coverage |
851| `get_service_detail(service_id)` | Public detail for a published service (includes docs, increments views) |
852| `get_service_pricing(service_id)` | Verified pricing with real-time x402 check |
853| `get_service_reviews(service_id, sort)` | List reviews for a service (public) |
854| `write_service_review(service_id, rating, comment)` | Submit/update a review (must have purchased or used first) |
855| `get_user_services(user_id)` | Get a user's published paid services (public, for profile display) |
856| `favorite_service(service_id)` | Add a service to favorites |
857| `unfavorite_service(service_id)` | Remove a service from favorites |
858| `get_favorite_services(cursor, limit)` | List the current user's favorite services |
859| `get_service_purchase_status(service_id)` | Check if the current user has purchased/used a service |
860| `get_service_earnings(service_id)` | Earnings stats for a single service (owner only) |
861| `get_earnings_summary()` | Earnings summary across all services (owner only) |
862| `get_service_onchain_records(service_id)` | On-chain USDC settlement records (owner only) |
863
864---
865
866## Usage from a bash block
867
868```bash
869python3 - <<'EOF'
870import sys
871# Prefer the registered skill tools (read this SKILL.md via read_file to
872# load them) over hand-written imports of exports.py. If you DO need a
873# direct import: the directory name has a HYPHEN, so dotted imports
874# (`from skills.community_publish import ...`) raise ModuleNotFoundError.
875# Use this sys.path pattern (or importlib.util.spec_from_file_location).
876sys.path.insert(0, "/data/workspace/skills/community-publish")
877from exports import (
878 # PUBLISH: public URL
879 publish_preview, unpublish_preview, list_published_previews,
880 # PUBLISH: open source code
881 open_source, remove_open_source, fork,
882 list_open_source, get_open_source, validate_open_source,
883 # LIST: free (project gallery)
884 list_in_dashboard, unlist_from_dashboard, get_listing_status,
885 # LIST: paid (service marketplace)
886 create_paid_service, submit_for_review, get_review_status,
887 publish_service, unpublish_service,
888 list_my_services, get_service, update_service, delete_service,
889 restore_service, set_service_examples, clear_service_examples,
890 # MARKETPLACE: browse + consumer actions
891 explore_marketplace, explore_services, get_service_detail,
892 get_service_pricing, get_service_reviews, write_service_review,
893 get_user_services, favorite_service, unfavorite_service,
894 get_favorite_services, get_service_purchase_status,
895 get_service_earnings, get_earnings_summary, get_service_onchain_records,
896 # Manual repair (rare)
897 link_to_listing,
898)
899
900# Step 1: Publish the URL
901print(publish_preview(preview_id="my-app-a3f1", slug="my-app"))
902
903# Step 2a: Free listing — show on gallery
904print(list_in_dashboard(slug="33-my-app", name="My App", description="A cool app"))
905
906# OR Step 2b: Paid listing — create service + review + publish
907res = create_paid_service(
908 name="My Paid App",
909 description="Premium features",
910 service_type="paid_project",
911 tags=["developer-tools"],
912 project_slug="33-my-app", # full published slug WITH user prefix
913 api_endpoint="https://community.iamstarchild.com/33-my-app",
914 provider_wallet="0xAbC...",
915 pricing_model="monthly",
916 price=5,
917 service_description="Subscribers get premium features.",
918)
919print(res)
920# Then: publish_service(res["service_id"]) — optionally submit_for_review() first for a self-check report
921EOF
922```
923
924---
925
926## Behavioral rules
927
928- **Show the diff before `open_source()`**. After `validate_open_source`, summarize what's about to be pushed and ask for confirmation. Exception: explicit "publish without confirmation" or re-publish of a known good project.
929- **Never auto-run setup.sh on fork**. Show the command, let the user confirm.
930- **Always collect env in one batch on fork**. Read project's `env_required`, diff against `workspace/.env`, call `request_env_input` ONCE with the missing keys.
931- **Review is required for publishing.** `publish_service()` requires `approved` status — always run `submit_for_review()` first. Show the report to the user; if rejected, fix with `update_service()` and re-run `submit_for_review()`. A check run against an already-listed service never delists it.
932- **`api_endpoint` must be the x402 charge endpoint.** For paid projects this is the project's public URL. For paid APIs it's the external API URL. The reviewer hits this URL expecting a `402`.
933- **Price unit is USDC.** The 402 response's `accepts.amount` is in **base units** (6 decimals for USDC). A `$0.01` price → `amount: "10000"`. Mismatch here is the #1 review failure.
934- **Don't fabricate review results.** Always call `get_review_status()` to check — never assume the review passed because you submitted it.
935- **Don't conflate publish and list.** `publish_preview()` allocates a URL. `list_in_dashboard()` / `create_paid_service()` makes it discoverable. These are separate, deliberate steps.
936- **Slug rules**: lowercase alphanumeric + hyphens, 3-50 chars, no leading/trailing hyphen.
937- **Version rules** (`open_source`): strict semver. Re-publishing same version is rejected.
938- **URL ≠ code ≠ listing**: a public URL going down does NOT remove the open-source code or the marketplace listing, and vice versa. They're independent.
939- **Do NOT pass `project_slug` for standalone `paid_api` services.** `project_slug` belongs to `paid_project` only — including the "free webpage + paid API" pattern (Flow D, which uses `paid_project`; passing `paid_api` + `project_slug` gets auto-upgraded to `paid_project` with a `project_slug_warning`). Passing a preview slug or non-existent slug for a standalone API creates a phantom association. The backend silently clears non-existent slugs, but you should not pass `project_slug` unless the user explicitly wants to link a free project page with the paid API.
940- **When the user asks for multiple APIs, create ONE service with `api_endpoints`.** Do NOT call `create_paid_service()` multiple times for related APIs. Use the `api_endpoints` array to list all endpoints in a single service (Flow E). Only create multiple services if the APIs are truly unrelated (different domains, different audiences, different pricing models).
941- **Default payment networks to `all`.** Never hard-code a single chain (e.g. `['eip155:8453']`) as the default — that re-introduces the old Base-only behavior. Omit `networks_mode` / `supported_networks` (or pass `networks_mode="all"`) so the service follows the platform mainnet set (Base + Monad + Robinhood + X Layer + Solana; new chains picked up automatically). Only use `networks_mode="custom"` + a non-empty `supported_networks` when the user explicitly asks to restrict to a subset ("only Base", "only Monad", etc.).
942- **`provider_wallet` is an EVM address used on every enabled EVM chain.** The Starchild facilitator settles to the same address on each EVM chain; it is NOT Base-only. Do not describe it as a "Base wallet" to the user. **For Solana payments**, the platform automatically uses the user's Privy Solana wallet address (`provider_sol_wallet`). If the user has not explicitly provided a Solana address, `create_paid_service()` auto-fetches it from the Privy wallet. Services without a Solana address will not accept Solana payments (Solana is excluded from the 402 accepts list).
943- **Gas for settlement is paid by the platform**, not the provider. Do not tell the provider they need to fund ETH/MON for settler gas.
944
945---
946
947## Common gotchas
948
949| Symptom | Cause | Fix |
950|---|---|---|
951| `publish_preview`: `Preview not found` | Wrong preview_id, or service was stopped | Check `/data/previews.json`, restart with `preview(action='serve')` |
952| `publish_preview`: `429 Too many published previews` | Hit 20-per-user gateway cap | `unpublish_preview()` something old first |
953| `publish_preview`: `FLY_MACHINE_ID not set` | Running locally, not in Starchild container | URL publish only works in the production container |
954| `list_in_dashboard`: `404 No preview found` | `publish_preview()` hasn't run for this slug yet | Call `publish_preview()` first |
955| `open_source`: `400 Validation failed: env names not in .env.example` | Listed `MY_KEY` in `env_required` but forgot `.env.example` | Add the missing key to `.env.example` |
956| `open_source`: `400 Possible secret detected` | Secret scanner found a real-looking API key | Move to env var; `.env.example` value should be `your-key-here` |
957| Marketplace shows service as free / missing after publish | Only `publish_preview()` was run — URL publish ≠ paid listing | Complete the chain: `create_paid_service` → `publish_service` |
958| `create_paid_service`: `400 Free services should be published through the Project publish flow` | Tried `service_type: "free_project"` | Use `list_in_dashboard()` for free projects, not `create_paid_service()` |
959| `publish_service`: `400 not in a publishable state` | Service is already listed, unavailable, or deleted | Check `get_service()` state; `unavailable` → `restore_service()` |
960| `submit_for_review`: `400 Free services do not require review` | The service record was created as a FREE type — the paid payload was built by hand (missing `service_type`/wallet/pricing) instead of via `create_paid_service()` | Delete it and recreate with `create_paid_service()` (all paid fields are required positional args, so this cannot happen through the function) |
961| Review rejected: `pricing_consistency` failed | 402 response `amount` doesn't match declared `price` | Ensure `amount` = `price * 1000000` (USDC 6 decimals) |
962| Review rejected: `api_reachable` failed | Endpoint doesn't return 402 | Wire up x402 charging on the endpoint first |
963| `create_paid_service` response has `project_slug_warning` | Passed `project_slug` for a `paid_api` but the slug doesn't exist in `project_listings` | Backend cleared it automatically. If this is a standalone API, don't pass `project_slug`. If you intended Flow D, `publish_preview()` + `list_in_dashboard()` the project first, then `update_service()` with the correct slug. |
964| `create_paid_service`: `500 Failed to create service` after delete→create cycles with the SAME name | Deleted services keep their slug (soft delete), and slug generation only tries a limited number of suffixes — repeated delete/recreate with one name exhausts them | Do NOT wait and retry — the failure is permanent for that name. Use a different service name, or `restore_service(service_id)` + `update_service()` instead of delete+recreate |
965| Created multiple services when user asked for "multiple APIs" | Called `create_paid_service()` once per API instead of using `api_endpoints` | Use Flow E: one `create_paid_service()` call with `api_endpoints=[...]` array. Only split into multiple services if the APIs are truly unrelated. |
966| Purchases not recorded for external API (own facilitator) | Service was created without `source="manual"`, so no proxy URL is generated and Starchild has no way to observe payments | Either switch to the Starchild facilitator (Option A) or recreate the service with `source="manual"` (Option B) |
967| Proxy URL returns 502 for `source="manual"` service | The `api_endpoint` URL is unreachable from Starchild servers | Verify the external API is publicly accessible and not behind a firewall |
968| Marketplace shows a chain the 402 `accepts` doesn't have (or vice versa) | The service `networks_mode` and the x402 gateway's `accepts` got out of sync — e.g. listing is `all` (Base+Monad) but the x402 gateway was monetized with `--networks eip155:8453` (custom, Base only) | Re-run the x402 skill's `monetize` without `--networks` (to follow `all`), OR `update_service(service_id, networks_mode="custom", supported_networks=[...])` to match the gateway. The two must agree. |
969| `create_paid_service` / `update_service` rejects with "supported_networks must be a non-empty list" | `networks_mode="custom"` was passed but `supported_networks` was missing, empty, or `None` | Pass a non-empty list of CAIP-2 ids (e.g. `["eip155:8453"]`), or switch to `networks_mode="all"` (the default) to accept all platform mainnets. |
970| Buyer can't pay on Monad (402 has no Monad `accepts`) but listing shows Monad | The x402 gateway was monetized before the multi-chain release, or with `--networks eip155:8453` | Re-run `monetize` without `--networks` so the 402 `accepts` array includes every platform mainnet. The listing `all` mode is correct; the gateway side is stale. |
971| Settlement fails on one chain but works on another | The Starchild facilitator's settler is out of gas on that chain (ETH for Base, MON for Monad) | Platform-side issue (gas is subsidized). The other chain keeps working. Report to ops — do NOT ask the provider to fund gas. |
972
973---
974
975## Cover Image Upload Flow
976
977**⚠️ MANDATORY — read this section whenever you need to set or change a cover image.**
978
979The gateway validates `cover_url` domains. Only `storage.googleapis.com`, `image.thum.io`,
980and `api.microlink.io` are accepted. **Do NOT use imgur, data URIs, or any other hosting.**
981
982### Quick path: `upload_cover_image()`
983
984```python
985from skills.community_publish.exports import upload_cover_image
986
987result = upload_cover_image("my-slug", "/path/to/image.png")
988# result = {"ok": True, "public_url": "https://storage.googleapis.com/..."}
989
990# Then use the URL:
991list_in_dashboard("my-slug", name="My Project", cover_url=result["public_url"])
992# or:
993create_paid_service(..., cover_url=result["public_url"])
994# or:
995update_service(service_id, cover_url=result["public_url"])
996```
997
998### What `upload_cover_image()` does internally
999
10001. **Presign** — calls `POST /api/projects/cover/presign` (container JWT via `Authorization: Bearer $CONTAINER_JWT`) with `slug`, `content_type`, `file_size`
10012. **Upload** — PUTs the raw image bytes to the GCS V4 signed URL
10023. **Returns** — the `public_url` on `storage.googleapis.com`
1003
1004### Supported formats
1005
1006- `image/png`, `image/jpeg`, `image/webp`
1007- Max 2MB — compress before uploading if needed
1008
1009### If the user provides a large image
1010
1011```python
1012# Compress first (PIL example)
1013from PIL import Image
1014import io
1015
1016img = Image.open("/path/to/large.png")
1017img.thumbnail((1200, 630)) # reasonable cover dimensions
1018buf = io.BytesIO()
1019img.save(buf, format="JPEG", quality=85)
1020buf.seek(0)
1021
1022# Save compressed version
1023compressed_path = "/tmp/cover_compressed.jpg"
1024with open(compressed_path, "wb") as f:
1025 f.write(buf.getvalue())
1026
1027# Upload
1028result = upload_cover_image("my-slug", compressed_path)
1029```
1030
1031### Common mistakes
1032
1033| Mistake | Why it fails | Fix |
1034|---|---|---|
1035| Using imgur URL as `cover_url` | Domain not in allowlist (project/internal routes reject with 400) | Use `upload_cover_image()` → GCS URL |
1036| Passing data URI as `cover_url` | Gateway returns 500 (URL too long / not a valid URL) | Save to file, then `upload_cover_image()` |
1037| Using thum.io to screenshot a preview page | Preview pages on internal ports are not publicly accessible | Use `upload_cover_image()` with the actual image file |
1038| Not reading the knowledge doc | Missing context on GCS config, path conventions, domain rules | Always check `starchild-knowledge/starchild-community-gateway/service-cover-upload.md` |
1039
1040---
1041
1042## Frontend presentation — Projects vs Services
1043
1044The web frontend has **two separate modals** for community content:
1045
1046| Modal | Content type | What it shows | Query functions |
1047|---|---|---|---|
1048| **ProjectMarketplaceModal** | Free projects | Card grid: cover image, name, description, tags, views, favorites | `explore_projects()`, `my_projects()`, `favorite_projects()`, `get_tab_counts()`, `get_popular_tags()`, `get_user_projects()`, `favorite_project()`, `unfavorite_project()` |
1049| **MarketplaceModal** | Paid services (x402) | Service cards: pricing, ratings, purchase buttons | `explore_services()`, `list_my_services()`, `get_service_detail()`, `get_service_tags()`, `get_featured_services()` |
1050
1051Both also appear in **AgentProfile** (Projects tab / Services tab) and the landing page.
1052
1053Each project has a **direct URL** (path-based `/{slug}` or subdomain `{slug}.community.iamstarchild.com`). The `/projects` and `/services` pages are frontend-rendered browse pages.
1054
1055### Projects query functions
1056
1057| Function | Data scope | Purpose |
1058|---|---|---|
1059| `explore_projects(search, tag, sort, limit, cursor)` | Public | Browse all public projects. Sort: `all` (newest) or `trending`. |
1060| `my_projects(tag)` | Personal | List the current user's published projects with stats. |
1061| `favorite_projects(tag, limit, cursor)` | Personal | List the current user's favorited projects. |
1062| `get_tab_counts()` | Personal | Get tab counts (explore, mine, favorites, purchased, services_mine, services_favorites). |
1063| `get_popular_tags()` | Public | Get popular project tags for filtering. |
1064| `get_user_projects(user_id, limit)` | Public | Get public projects by a specific user (for profile pages). |
1065| `favorite_project(slug)` | Personal | Add a project to the current user's favorites. |
1066| `unfavorite_project(slug)` | Personal | Remove a project from the current user's favorites. |
1067
1068### Services query functions
1069
1070| Function | Data scope | Purpose |
1071|---|---|---|
1072| `explore_services(search, sort, tags, ...)` | Public | Browse standalone paid services only. |
1073| `list_my_services(cursor, limit)` | Personal | List the current user's paid services. |
1074| `get_service_detail(service_id)` | Public | Public detail for a published service. |
1075| `get_service_pricing(service_id)` | Public | Verified pricing info (real-time x402 verification). |
1076| `get_service_reviews(service_id, sort, cursor, limit)` | Public | List reviews for a service. |
1077| `write_service_review(service_id, rating, comment, is_anonymous)` | Personal | Submit or update a review (upsert). |
1078| `get_service_tags()` | Public | Get predefined service tags with i18n names. |
1079| `get_featured_services()` | Public | Get featured services for homepage display. |
1080| `get_user_services(user_id, limit)` | Public | Get published paid services by a specific user. |
1081| `favorite_service(service_id)` | Personal | Add a service to favorites. |
1082| `unfavorite_service(service_id)` | Personal | Remove a service from favorites. |
1083| `get_favorite_services(cursor, limit)` | Personal | List the current user's favorite services. |
1084| `get_service_purchase_status(service_id)` | Personal | Check if user has purchased/used a service. |
1085| `get_service_earnings(service_id)` | Personal | Get earnings stats for a service (owner only). |
1086| `get_earnings_summary()` | Personal | Get earnings summary across all services. |
1087| `get_service_onchain_records(service_id, cursor, limit)` | Personal | Get on-chain transaction records (owner only). |
1088
1089---
1090
1091## References
1092
1093- `lib/manifest.py` — project.yaml parser/writer + semver helpers
1094- `lib/validate.py` — local pre-publish validation (mirrors gateway-side checks)
1095- `lib/install.py` — type-specific install handlers (task/service/script)
1096- `lib/gateway.py` — HTTP client for `/api/register` (URL), `/api/code-projects/*` (code), `/api/projects-query/*` (free listing + browse), `/api/services/*` (paid listing), `/api/projects/cover/presign` (cover upload)