Community Publish

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.

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

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.

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:

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

Routing — match user intent to the right action

A. Status intents — user wants to know current state

B. Action intents — user wants to change state

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.

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:

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:

⚠️ Common Flow confusion mistakes (from real incidents)

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):

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

1. Have a running project with a public URL (via publish_preview()).
2. 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.
3. 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.

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

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

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

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

3. Run review → same as Flow B step 4 (required before publishing).
4. 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.

1. Publish the project via publish_preview() — this creates the free landing page.
2. Configure x402 charging on the API endpoint (e.g. /api/random returns 402).
3. 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.

4. 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).

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

2. 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)