# Agent Marketplace Quickstart

Give a coding agent a secure, additive path for adding optional Zoneless USDC seller payouts to an existing marketplace.

This is the stable bootstrap document for a coding agent. The agent must preserve checkout and every existing payout method, work in test mode, and stop at the human authorization and production secret boundaries.

> **Collecting payments from customers instead?** Use the [Agent Payments Quickstart](/agent-payments-quickstart) when the goal is USDC subscriptions or checkout rather than paying sellers out.

> **Assume no crypto knowledge** Explain every human action in plain language. USDC is a digital dollar; Solana is the network carrying it; SOL pays the small network fee in live mode; a public wallet address is safe to share, while its secret key authorizes spending and must remain private. Test mode uses fake USDC, so they can send a test payout without a wallet, a faucet, or the live Solana network. Always distinguish test funds from real funds.

## 1. Start secure setup

From the marketplace repository, infer a clear platform name and run the command below. The Node.js CLI is only the secure bootstrap tool; it does not require the marketplace backend itself to use Node.js.

If setup reports that local profiles already exist for a different platform, retry with `--new-platform`. Reuse profiles that already belong to this marketplace.

### Terminal

```javascript
npx @zoneless/cli@latest agent setup \
  --platform-name "<marketplace name>" \
  --skill marketplace \
  --json
```

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

> **Do not handle secrets.** Never request, read, print, export, transmit, or commit an API key, wallet private key, seed phrase, or secret-manager value.

## 3. Read 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](/api-quickstart), use [llms.txt](https://docs.zoneless.com/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.

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

## 5. Choose 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&rsquo;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.

## 6. Add 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.

## 7. Verify 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.

## 8. Hand production setup back to the human

Report changed files, migrations, deployment commands, required environment-variable names, test-mode onboarding steps, tests run, and anything still unverified. Tell the human where to configure the API key and webhook secret without requesting either value.

Before an end-to-end test payout, tell the human to add test USDC from the dashboard **Balance** page (**Add test USDC**) or with `POST /v1/test_helpers/treasury/topups`. Create the payout, then process it with the same `processAll` / build and broadcast path as live. Simulated settlement does not need a wallet, faucet, or Devnet: broadcast the unsigned dummy transaction. Do not assume create returns `paid`. Self-hosters who set `SETTLEMENT_RAIL=onchain` should follow [Local Development](/local-development) instead.

Explain the live promotion explicitly: configure the separately provisioned live API key and `https://api.zoneless.com` in the deployment secret manager, configure the live webhook secret, fund the live platform wallet, and complete one supervised payout before enabling live traffic.

The human must run the wallet backup command themselves in an interactive terminal, place the backup's `secretKeyBase58` value directly in the production secret manager as `SOLANA_SECRET_KEY`, and securely delete the temporary export. They must then follow [Fund your platform wallet](/fund-platform-wallet) to add enough USDC for seller payouts and a small amount of SOL for Solana network fees, configure live webhooks, and approve a supervised end-to-end payout.

> **Production remains a human decision.** Do not claim the integration is production-ready until secret provisioning, wallet funding, live webhook setup, and a supervised payout are complete.

### Human-only command

```javascript
npx @zoneless/cli@latest wallet backup --output <secure-path>
```