Agent Marketplace Quickstart

2Pause for human authorization

Show the activation URL and code returned by the CLI, then wait for the human to review and approve the request. Never approve it for them. Setup provisions test and live profiles while keeping API credentials and wallet secrets out of the prompt and source tree.

The CLI binds this repository to the provisioned profiles in .zoneless/project.json and selects test by default. Build and verify with https://api-test.zoneless.com; keep mode environment-driven and leave live promotion to the human handoff.

Setup validates stored keys before reuse. If it reports credentials_invalid, run zoneless auth reconnect --json and show the new authorization prompt to the human. For local testing, run zoneless env sync --include-wallet --json; it finds an unambiguous env file, preserves unrelated values, and writes the bound test credentials without displaying them. Use --target only when the project has multiple env files.

3Read the installed marketplace skill

After approval, parse the successful JSON response and read the file at skill_path before changing application code. The CLI installs the versioned zoneless-marketplace skill locally and returns its exact path, so this flow does not depend on automatic skill discovery.

Follow that skill as the implementation and safety contract. Start with the API Quickstart, use llms.txt as an index, and read other resource pages only when implementing that resource or when blocked. Do not fetch the entire documentation set upfront.

4Classify the money flow before editing

Inspect checkout separately from payouts. Determine whether the marketplace accrues seller earnings for a later payout (including Stripe separate charges and transfers), pays sellers during checkout using destination charges, direct charges, or split payments, or is a small/file-backed app with no withdrawal infrastructure.

Preserve every existing provider. If sellers are paid during checkout, keep that path unchanged for existing providers; for a Zoneless seller, collect on the platform and accrue that sale once for a later Zoneless payout. For a small app, use its existing storage and process model rather than adding queues, locks, authentication, or production infrastructure.

5Choose the native integration path

• JavaScript or TypeScript backend: centralize one server-side @zoneless/node client. Use payouts.processAll() or processBatch() for platform-wide pending payouts, or the SDK’s build, sign, and broadcast methods when processing explicit payout IDs.
• Python, Ruby, Go, or another runtime: use the project's existing HTTP client to build a small centralized adapter for the canonical REST API. Do not add Node.js as an application runtime dependency.

Keep API keys and transaction signing server-side and use https://api-test.zoneless.com during integration. The Node SDK already handles Solana transaction building and signing: do not add Solana packages or application configuration for mint, cluster, RPC, token accounts, or platform account IDs. Non-Node runtimes use the documented build and broadcast endpoints with a maintained signer for that language.

Match the existing payout trigger: use processAll() for a scheduled worker that owns every pending Zoneless payout, processBatch() for one bounded platform batch, and explicit build/sign/broadcast for a seller claim or admin-selected payout ID. Do not add both a claim route and a scheduler unless the marketplace already supports both.

6Add Zoneless without replacing anything

• Add zoneless as a separate opt-in payout method and store a dedicated zonelessAccountId.
• Create and persist an Express connected account, then use a hosted Account Link for seller onboarding.
• Treat payouts_enabled or a verified account.updated webhook as onboarding completion.
• Pin each sale or earning to one provider. If the existing checkout pays sellers immediately, leave that behavior unchanged for existing providers and omit the destination transfer only for Zoneless sellers. Never pay one sale through both checkout and Zoneless.
• Transfer the seller's accrued earnings to their connected-account balance, then create the payout with zonelessAccount or the Zoneless-Account header. Do not use destination for the connected account ID.
• Reuse the existing ledger, storage, jobs, idempotency conventions, webhook route, and UI styles. Keep the implementation proportional to the application and do not refactor unrelated code.
• If a broadcast response is lost, retrieve the payout status before retrying. Never create a replacement transfer or payout; reconcile a paid result, or rebroadcast the same retained signed transaction when the payout remains pending and that transaction is available.

7Verify in test mode

Add focused tests that prove the existing checkout and payout path is unchanged, seller opt-in works, one sale cannot be paid through two providers, connected-account context and stable idempotency keys are used, and no secrets reach browser code or fixtures. For destination charges, test that Stripe sellers still use them and Zoneless sellers do not.

Run the project's formatter, focused tests, linter, type checker, and build. Use mocks or test credentials only. Do not create live-mode application data, fund a wallet, submit a transaction, broadcast a payout, or switch production traffic.