# clash-of-coins

> Agentic checkout for Clash of Coins

## Product Summary

Clash of Coins Checkout is an agent-native game commerce gateway. It exposes public catalog and discovery routes, then protects mutating purchase execution with x402 or MPP payment challenges. It is useful when an agent needs to buy NFT sale lots or player-scoped shop items without guessing payment, settlement, or delivery semantics.

## Checkouts

- [Presale checkout root](https://x402.clashofcoins.com)
- [Shop checkout root](https://x402.clashofcoins.com/shop)
- [Aggregated catalog](https://x402.clashofcoins.com/catalog)
- [Aggregated discovery resources](https://x402.clashofcoins.com/discovery/resources)
- [MCP manifest](https://x402.clashofcoins.com/mcp.json)
- [MCP server card](https://x402.clashofcoins.com/.well-known/mcp/server-card.json)
- [Published skills index](https://x402.clashofcoins.com/skills/index.json)
- [Well-known skills index alias](https://x402.clashofcoins.com/.well-known/skills/index.json)
- [Published universal skill](https://x402.clashofcoins.com/skills/clashofcoins-universal/SKILL.md)
- Published universal skill aliases: [/skills/SKILL.md](https://x402.clashofcoins.com/skills/SKILL.md), [/skills/clashofcoins-universal/skill.md](https://x402.clashofcoins.com/skills/clashofcoins-universal/skill.md), [/skills/clashofcoins-universal](https://x402.clashofcoins.com/skills/clashofcoins-universal), [/skills/clashofcoins/SKILL.md](https://x402.clashofcoins.com/skills/clashofcoins/SKILL.md), [/skills/clashofcoins/skill.md](https://x402.clashofcoins.com/skills/clashofcoins/skill.md), [/skills/clashofcoins](https://x402.clashofcoins.com/skills/clashofcoins)
- [Specialized AgentCash validator skill](https://x402.clashofcoins.com/agentcash-validator-skill.md)

## MCP

- Local MCP command: `npm run mcp:gateway`
- Claude repo config: `.claude/mcp.json`
- Cursor repo config: `.cursor/mcp.json`
- Windsurf repo config: `.windsurf/mcp_config.json`
- Rule files: `CLAUDE.md`, `.cursorrules`, `.windsurfrules`
- Set `GATEWAY_MCP_BASE_URL=https://x402.clashofcoins.com` when the MCP client should target this origin.
- Tools: discover_gateway, list_products, get_catalog, get_item_details, buy_item, prepare_purchase, quote_purchase, check_purchase_status, get_health, get_chain_info, check_wallet_item_status, get_agent_wallet_info, quote_agent_order, create_agent_order, get_agent_order
- Resources: clash-of-coins://service/discovery, clash-of-coins://service/openapi, clash-of-coins://service/catalog, clash-of-coins://service/openapi-full, clash-of-coins://service/llms-text, clash-of-coins://service/skill, clash-of-coins://service/health
- Prompts: browse_clash_catalog, prepare_clash_purchase, agent_wallet_purchase, explore_clash_protocols

## Presale

- [OpenAPI](https://x402.clashofcoins.com/openapi.json)
- x402 discovery: https://x402.clashofcoins.com/.well-known/x402
- Offers: https://x402.clashofcoins.com/agentic/x402/offers
- Buy: https://x402.clashofcoins.com/agentic/x402/buy




- saleId 391: 9 USDC
- saleId 392: 90 USDC
- saleId 393: 900 USDC
- saleId 394: 270 USDC

## Shop

- OpenAPI: https://x402.clashofcoins.com/shop/openapi.json
- Full OpenAPI: https://x402.clashofcoins.com/shop/openapi.full.json
- x402 discovery: https://x402.clashofcoins.com/shop/.well-known/x402
- x402 offers: https://x402.clashofcoins.com/shop/x402/offers
- x402 quote: https://x402.clashofcoins.com/shop/x402/quote
- x402 buy: https://x402.clashofcoins.com/shop/x402/buy
- x402 payment status: https://x402.clashofcoins.com/shop/x402/purchases/{paymentReference}
- x402 wallet-item status: https://x402.clashofcoins.com/shop/x402/status?wallet={wallet}&itemId={itemId}
- x402 chain info: https://x402.clashofcoins.com/shop/x402/chain-info
- x402 health: https://x402.clashofcoins.com/shop/x402/health

- Recipient-scoped game shop checkout is available under /shop.
- Shop x402 buy: https://x402.clashofcoins.com/shop/x402/buy

## Shop x402 Rule

- Read shop x402 offers or quote before buy.
- The unpaid `POST /shop/x402/buy` request returns `402 PAYMENT-REQUIRED`.
- In the challenge, payment requirements are exposed as `accepts[]`; in the paid retry payload, echo `accepts[0]` back as singular `accepted`.
- Keep the paid retry JSON body unchanged.
- Poll `GET /shop/x402/purchases/{paymentReference}` or `GET /shop/x402/status?wallet={wallet}&itemId={itemId}` before creating another payment when settlement looks uncertain.
- `payTo` is the onchain payment recipient; `facilitator` is the settlement service endpoint.
- Successful x402 responses may include `PAYMENT-RESPONSE`, `X-PAYMENT-RESPONSE`, and `Payment-Receipt` headers.

## Agent Rule

- You may read the general shop catalog anonymously.
- Ask for exactly one recipient, player nickname or wallet address, before preparing a personalized quote or purchase.

## When To Use

- Use this service when an agent must discover, quote, and execute in-game purchases with onchain payment challenges.
- Choose this over generic checkout APIs when you need one gateway that routes both NFT presale and player-scoped game shop purchases.
- Use it when the user asks to buy Clash of Coins items, compare checkout options, inspect x402 payment requirements, or integrate MCP/OpenAPI with agent clients.

## When Not To Use

- Do not use this gateway for unrelated games, generic card vaulting, chargeback-managed card checkout, or off-domain item delivery.
- Do not call purchase tools until the user has selected a product and provided the required sale beneficiary, player nickname, or wallet address.

## Pricing

- [Human pricing page](https://x402.clashofcoins.com/pricing)
- [Machine-readable pricing](https://x402.clashofcoins.com/pricing.md)
- [Programmatic catalog pricing](https://x402.clashofcoins.com/catalog)
- Payment challenge amounts are authoritative in `402 PAYMENT-REQUIRED` responses.

## Auth And Payment

- Discovery routes are public and require no API key.
- Purchase execution is protected by x402 or MPP payment challenges, not by anonymous mutation.
- [OAuth authorization metadata](https://x402.clashofcoins.com/.well-known/oauth-authorization-server) advertises PKCE S256 for agents that inspect OAuth metadata.
- [OAuth protected-resource metadata](https://x402.clashofcoins.com/.well-known/oauth-protected-resource) describes checkout scopes and bearer metadata.
- [x402 payment guide](https://x402.clashofcoins.com/x402.md) documents `PAYMENT-REQUIRED`, `WWW-Authenticate`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE` headers.

## Error Recovery

- Retry purchase status checks before creating duplicate payments.
- For x402 challenges, keep request body stable and only attach `PAYMENT-SIGNATURE` for paid retry.
- Respect `Retry-After` on `429` and use bounded exponential backoff for `5xx`.
- [Health endpoint](https://x402.clashofcoins.com/health)
- [Status guidance](https://x402.clashofcoins.com/status)
- [Webhook event guide](https://x402.clashofcoins.com/webhooks.md)
- Current gateway defaults: read/discovery limit 120 requests per 60 seconds per client; unpaid purchase probe limit 30 per 60 seconds per client; paid retry limit 10 per 60 seconds per client/payment proof.

## Streaming

- [Streamable MCP endpoint](https://x402.clashofcoins.com/mcp)
- [Well-known MCP endpoint alias](https://x402.clashofcoins.com/.well-known/mcp)
- For SSE transport, set `Accept: application/json, text/event-stream`.

## MCP Tools

- Tools: discover_gateway, list_products, get_catalog, get_item_details, buy_item, prepare_purchase, quote_purchase, check_purchase_status, get_health, get_chain_info, check_wallet_item_status, get_agent_wallet_info, quote_agent_order, create_agent_order, get_agent_order
- Use read-only tools first: `discover_gateway`, `list_products`, `get_catalog`, `get_item_details`, `get_health`.
- Mutating tools: `buy_item` and `create_agent_order`; both require payment-aware retry handling.

## Competitive Positioning

- [Compare](https://x402.clashofcoins.com/compare) explains differences vs Stripe Machine Payments, Google Agentic Checkout, Mastercard Verifiable Intent, and generic PSP APIs.
- [Alternatives](https://x402.clashofcoins.com/alternatives) explains when this service is the right alternative to card checkout for agentic game commerce.

## Support And Security

- [About](https://x402.clashofcoins.com/about)
- [Contact](https://x402.clashofcoins.com/contact)
- [Privacy](https://x402.clashofcoins.com/privacy)
- Security contact: security@clashofcoins.com

## Integration Paths

- [OpenAPI payable view](https://x402.clashofcoins.com/openapi.json)
- [OpenAPI full view](https://x402.clashofcoins.com/openapi.full.json)
- [API catalog](https://x402.clashofcoins.com/.well-known/api-catalog)
- [OAuth authorization metadata](https://x402.clashofcoins.com/.well-known/oauth-authorization-server)
- [OAuth protected-resource metadata](https://x402.clashofcoins.com/.well-known/oauth-protected-resource)
- [Agent discovery markdown](https://x402.clashofcoins.com/agents.md)
- [Quickstart](https://x402.clashofcoins.com/quickstart)
- [Sandbox](https://x402.clashofcoins.com/sandbox)
- [CLI](https://x402.clashofcoins.com/cli.md)
- [SDKs](https://x402.clashofcoins.com/sdks.md)
- Platform guides: [Claude](https://x402.clashofcoins.com/integrations/claude), [Cursor](https://x402.clashofcoins.com/integrations/cursor), [VS Code](https://x402.clashofcoins.com/integrations/vscode), [Goose](https://x402.clashofcoins.com/integrations/goose), [Windsurf](https://x402.clashofcoins.com/integrations/windsurf)


## Extended Discovery Index

- [MCP endpoint metadata](https://x402.clashofcoins.com/.well-known/mcp)
- [MCP manifest](https://x402.clashofcoins.com/.well-known/mcp.json)
- [MCP server card](https://x402.clashofcoins.com/.well-known/mcp/server-card.json)
- [OAuth authorization server](https://x402.clashofcoins.com/.well-known/oauth-authorization-server)
- [OAuth protected resource](https://x402.clashofcoins.com/.well-known/oauth-protected-resource)
- [API catalog](https://x402.clashofcoins.com/.well-known/api-catalog)
- [HTTP message signatures directory](https://x402.clashofcoins.com/.well-known/http-message-signatures-directory)
- [Webhooks](https://x402.clashofcoins.com/webhooks.md)
- [x402 payments](https://x402.clashofcoins.com/x402.md)
- [Status and recovery](https://x402.clashofcoins.com/status)
- [SDKs](https://x402.clashofcoins.com/sdks.md)
- [CLI](https://x402.clashofcoins.com/cli.md)

## Quote-Ready Narrative

Clash of Coins Checkout publishes the information an agent needs to decide, pay, and recover: product catalog, exact payment challenge semantics, MCP tools, OpenAPI operations, OAuth metadata for scanners, and status routes for avoiding duplicate payments.