Agent guide

Start here for LLM agents, Cursor, and CI automation. Machine-readable index: /llms.txt. OpenAPI contract: openapi/openapi.json.

Bootstrap flow

• POST /auth/signup or POST /auth/login → JWT
• POST /auth/verify-email with token from email (required before writes)
• POST /auth/api-keys with scopes (JWT only) → launa_live_... (production) or launa_sandbox_... (Sandbox) key (shown once)
• Use API key for automation: header X-API-Key: launa_live_... or launa_sandbox_...
• Sandbox / Test mode (fork payments, funded wallet): Sandbox — CLI launa --sandbox …

Environment pairing

API key environment is fixed by prefix — it cannot be overridden with LAUNA_SANDBOX or X-Launa-Environment when using API keys.

Wrong pairing → 401 {"error":"invalid token"} (not a scope issue).

JWT clients can target Sandbox on either control-plane host via X-Launa-Environment: development or CLI --sandbox; API keys must use the matching base URL above.

Scope presets

• readonly — apis:read, endpoints:read, domains:read, stats:read, settlements:read, openapi:read
• apiManager — apis/endpoints/domains read+write, openapi:read
• analytics — stats:read, settlements:read

CLI: launa scopes presets --json

Wrap an upstream API

1. GET /config/platform
2. POST /apis { name, slug, upstream_base_url, pay_to_mode, pay_to_address? }
3. POST /apis/{id}/endpoints { method, path_pattern, accepts[] }
4. Gateway URL: https://{slug}.{platform_domain}{path}

Import OpenAPI

1. POST /openapi/parse { spec: "<yaml or json>" }  → operations[] (includes request_schema/response_schema when present)
2. POST /apis/{id}/openapi/import { operations[], accepts[] }

Discovery

1. GET /apis/{id}/discovery → openapi_url, well_known_url for all verified hosts
2. GET https://{host}/openapi.json  (AgentCash)
3. GET https://{host}/.well-known/x402.json
4. npx -y @agentcash/discovery@latest check "https://{host}/"

See API discovery.

Custom domain

1. POST /apis/{id}/domains { hostname }
2. Response includes verification_record, cname_target, verification_token
3. POST /apis/{id}/domains/{domainId}/verify

CLI quick reference

launa apis list --json
launa apis create --name "My API" --slug my-api --upstream https://api.example.com \
  --discovery-guidance "Use GET /v1/*." --json
launa apis discovery --id ID --json
launa discovery urls --api-id ID --json
launa apis get --id ID --json
launa apis delete --id ID --json
launa endpoints list --api-id ID --json
launa endpoints create --api-id ID --method GET --path "/v1/*" --price-usdc 0.10 --json
launa endpoints update --api-id ID --endpoint-id EP --request-schema '{"type":"object"}' --json
launa endpoints delete --api-id ID --endpoint-id EP --json
launa domains suggest --apex example.com --json
launa domains add --api-id ID --hostname api.example.com --json
launa domains verify --api-id ID --domain-id DOM --json
launa keys list --json
launa keys create --name ci --scopes apis:read,apis:write --json
launa keys revoke --id KEY --json
launa auth login --email you@example.com --password secret --json
launa openapi parse --file spec.yaml --json
launa openapi import --api-id ID --file spec.yaml --price-usdc 0.10 --json
launa stats overview --days 30 --json
launa config platform --json
launa networks supported --json
launa pay url --url https://my-api.launa.io/v1/foo --json

Full details: CLI reference. Exit codes: 0 success, 1 API error, 2 usage error.

MCP tools

Requires LAUNA_API_KEY and LAUNA_BASE_URL (API key only — no JWT). Pair the key prefix with the correct base URL — see Environment pairing.

Discovery-related:

• launa_discovery_urls — apis:read
• launa_set_discovery_guidance — apis:write
• launa_update_endpoint_schemas — endpoints:write
• launa_create_api — apis:write + verified email (optional discovery fields)
• launa_import_openapi — openapi:read

Common seller tools: launa_list_apis, launa_get_api, launa_list_endpoints, launa_add_endpoint, launa_add_domain, launa_verify_domain, launa_domain_suggest, launa_stats_overview, launa_supported_networks, launa_platform_config.

Buyer: launa_inspect_url, launa_pay_url (needs LAUNA_EVM_PRIVATE_KEY and/or Hedera keys).

Full tool list: MCP server · API discovery

Buyer payments

Pay gateway hostnames, not the seller API. Example: https://my-api.launa.io/v1/foo. Full guide: Buyer clients.

# Inspect 402 requirements (no wallet spend)
launa inspect url --url https://my-api.launa.io/v1/foo --json
# Pay with funded wallet
export LAUNA_EVM_PRIVATE_KEY=0x...
launa pay url --url https://my-api.launa.io/v1/foo --json

• TypeScript: buyerClientFromEnv() + client.pay() — exact and batch-settlement
• Go: buyer.NewFromPrivateKey + Get(ctx, url) — exact and batch-settlement
• Python: BuyerClient.from_env().get(url) or AsyncBuyerClient — exact and batch-settlement
• MCP: launa_pay_url when wallet credentials are set
• Browser SPA: React paywall

Protocol: x402-foundation/x402.

Errors

JSON body: {"error":"message"}. Common:

• 401 unauthorized / invalid token
• 403 insufficient scope / email verification required / jwt required
• 409 email already registered / slug already exists

Idempotency

• POST /apis duplicate slug → 409
• OpenAPI import skips existing method+path keys
• Domain verify on already-verified domain → status already verified