/marketplace - HoloScript Marketplace API

Command: $ARGUMENTS

You are the agent surface for @holoscript/marketplace-api. Do not rebuild marketplace, x402, plugin, skill, or AST asset flows ad hoc. Use the shipped Express routes in packages/marketplace-api/src/server.ts.

Source Files

Environment

Load credentials from the local environment first:

MARKETPLACE_API_URL="${MARKETPLACE_API_URL:-http://localhost:3000/api/v1}"
MARKETPLACE_AUTH_TOKEN="${MARKETPLACE_AUTH_TOKEN:-}"

Server startup:

pnpm --filter @holoscript/marketplace-api dev

Useful server env:

Health And Discovery

curl -s "$MARKETPLACE_API_URL/health"
curl -s "$MARKETPLACE_API_URL/metrics"
curl -s "$MARKETPLACE_API_URL/plugins-health"
curl -s "$MARKETPLACE_API_URL/skills/search?limit=5"

Canonical Routes

Trait Flows

Search:

curl -s "$MARKETPLACE_API_URL/traits?q=physics&platform=web&verified=true&limit=10"
curl -s "$MARKETPLACE_API_URL/traits/popular?limit=10"
curl -s "$MARKETPLACE_API_URL/traits/recent?limit=10"

Publish requires Authorization: Bearer <token>:

curl -s -X POST "$MARKETPLACE_API_URL/traits" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo_trait",
    "version": "1.0.0",
    "description": "Reusable trait published through the marketplace API.",
    "license": "MIT",
    "keywords": ["demo"],
    "platforms": ["web"],
    "category": "utility",
    "source": "trait demo_trait { }"
  }'

Download and stats:

curl -s "$MARKETPLACE_API_URL/traits/<trait-id>/download?version=1.0.0"
curl -s "$MARKETPLACE_API_URL/traits/<trait-id>/stats"

Verify a creator:

curl -s "$MARKETPLACE_API_URL/users/<user-id>/verification"
curl -s -X POST "$MARKETPLACE_API_URL/verification" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"email","value":"creator@example.com"}'

Skill Marketplace Flows

Search and inspect:

curl -s "$MARKETPLACE_API_URL/skills/search?q=workflow&pricing=free&limit=10"
curl -s "$MARKETPLACE_API_URL/skills/categories"
curl -s "$MARKETPLACE_API_URL/skills/<skill-id>"

Publish:

curl -s -X POST "$MARKETPLACE_API_URL/skills/publish" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d @skill-package.json

Purchase and download paid skills:

curl -i -X POST "$MARKETPLACE_API_URL/skills/<skill-id>/purchase" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN"

curl -s "$MARKETPLACE_API_URL/skills/<skill-id>/download" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "X-Payment-ID: <x402-receipt-id>"

Install and verify:

curl -s -X POST "$MARKETPLACE_API_URL/skills/<skill-id>/install" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspacePath":"C:/path/to/workspace"}'

curl -s -X POST "$MARKETPLACE_API_URL/skills/<skill-id>/test" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Run the skill smoke prompt"}'

Plugin Marketplace Flows

Search and inspect:

curl -s "$MARKETPLACE_API_URL/plugins?q=renderer&signed=true&limit=10"
curl -s "$MARKETPLACE_API_URL/plugins/<plugin-id>"
curl -s "$MARKETPLACE_API_URL/plugins/<plugin-id>/versions"
curl -s "$MARKETPLACE_API_URL/plugins/<plugin-id>/provenance"

Publish:

curl -s -X POST "$MARKETPLACE_API_URL/plugins" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d @plugin-package.json

Purchase, download, and install-plan:

curl -i -X POST "$MARKETPLACE_API_URL/plugins/<plugin-id>/purchase"

curl -s "$MARKETPLACE_API_URL/plugins/<plugin-id>/download?version=1.0.0" \
  -H "X-Payment-ID: <x402-receipt-id>"

curl -s -X POST "$MARKETPLACE_API_URL/plugins/<plugin-id>/install-plan" \
  -H "Content-Type: application/json" \
  -d '{"targetStudioVersion":"7.0.0","targetPlatform":"web","installDependencies":true}'

Verify signing keys and reputation:

curl -s -X POST "$MARKETPLACE_API_URL/keys" \
  -H "Authorization: Bearer $MARKETPLACE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"<ed25519-or-rsa-public-key>","label":"creator laptop"}'

curl -s "$MARKETPLACE_API_URL/authors/<author-id>"

Hololand x402 Flows

Callback endpoint used by facilitators:

curl -s -X POST "$MARKETPLACE_API_URL/payments/x402/callback" \
  -H "Content-Type: application/json" \
  -d @x402-callback.json

Protected creation routes return 402 until a valid x402 payment is attached:

curl -i -X POST "$MARKETPLACE_API_URL/create-vrr-twin" \
  -H "Content-Type: application/json" \
  -d '{"business_id":"biz_123","geo_location":"33.4484,-112.0740","inventory_api":"https://example.com/inventory"}'

curl -i -X POST "$MARKETPLACE_API_URL/create-quest" \
  -H "Content-Type: application/json" \
  -d '{"business_id":"biz_123","narrative":"Guide visitors through the venue."}'

curl -i -X POST "$MARKETPLACE_API_URL/mint-story_weaver-book" \
  -H "Content-Type: application/json" \
  -d '{"world_id":"world_123"}'

Read-side routes:

curl -s "$MARKETPLACE_API_URL/business/<business-id>/vrr-twin"
curl -s "$MARKETPLACE_API_URL/agent/<agent-id>/quests"

AST Asset x402 Flows

Register and list:

curl -s -X POST "$MARKETPLACE_API_URL/ast-assets" \
  -H "Content-Type: application/json" \
  -d '{"source":"object demo { }","author":"agent","assetId":"demo-asset"}'

curl -s "$MARKETPLACE_API_URL/ast-assets"
curl -s "$MARKETPLACE_API_URL/ast-assets/<asset-id>/manifest"

Retrieve gated source:

curl -i "$MARKETPLACE_API_URL/ast-assets/<asset-id>"
curl -s "$MARKETPLACE_API_URL/ast-assets/<asset-id>" \
  -H "X-PAYMENT: <base64-x402-payload>"

Agent Rules

• Read the relevant route file before claiming a route does or does not exist.
• Use Authorization: Bearer $MARKETPLACE_AUTH_TOKEN for protected publish, rate, install, key, unpublish, and verification calls.
• Treat 402 as an expected x402 challenge, not a server failure.
• Preserve WWW-Authenticate, X-PAYMENT, X-PAYMENT-RESPONSE, and X-Payment-ID headers in payment flows.
• For local smoke tests, prefer in-memory services through createApp() unless the task explicitly requires Postgres/Railway validation.

Smoke Verification

Run this after editing the skill or marketplace route surface:

pnpm verify:claude-plugin-skills
pnpm verify:marketplace-skill
pnpm --filter @holoscript/marketplace-api exec vitest run src/__tests__/server-startup.test.ts src/__tests__/SkillMarketplacePayment.test.ts src/__tests__/PluginMarketplace.test.ts