{
  "markdown": "# KnowMint\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Deploy: Cloudflare Workers](https://img.shields.io/badge/Deploy-Cloudflare%20Workers-orange)](https://developers.cloudflare.com/workers/)\n\n**The first knowledge marketplace where AI agents pay directly with SOL — autonomously.**\n\nHumans list tacit knowledge, experiential insights, and battle-tested solutions. AI agents (Claude Code, ElizaOS, AgentKit) autonomously discover, evaluate, and purchase via the x402 protocol — paying sellers directly via non-custodial Solana P2P transfers. No private keys held by the platform.\n\n> Human-in-the-loop mode also available: agent searches and proposes, you approve. Same marketplace, your choice of autonomy level.\n\nThree access layers: **Web UI** / **CLI (`km`)** / **REST API + MCP Server**\n\n### Web UI\n![WebUI Purchase Flow](scripts/demo/recordings/webui-demo.gif)\n\n### CLI / MCP (for AI Agents)\n![AI Agent Autonomous Purchase Demo](scripts/demo/recordings/autonomous-purchase.gif)\n\n---\n\n## Why KnowMint\n\n- **First for agentic payments** — AI agents autonomously pay with SOL via x402 protocol. No human required to complete a purchase\n- **x402 autonomous purchasing** — HTTP 402 + Solana P2P direct transfer. Agent finds, pays, and accesses knowledge end-to-end\n- **Human-in-the-loop also available** — Agent proposes, you approve. Same marketplace, your choice of autonomy level\n- **Human → AI knowledge supply** — Sell experiential and tacit knowledge that AI cannot self-generate\n- **Non-custodial payments** — Buyer-to-seller P2P direct transfer on Solana (no platform custody)\n\n---\n\n## For AI Agents\n\n### Getting an API Key\n\n**For AI agents (wallet-based, no web UI needed):**\n\n1. `POST /api/v1/auth/challenge` with `{ \"wallet\": \"<base58>\", \"purpose\": \"register\" }`\n2. Sign the returned `message` with your Solana wallet\n3. `POST /api/v1/auth/register` with `{ \"wallet\", \"signature\", \"nonce\" }`\n4. Receive `{ \"api_key\": \"km_...\", \"user_id\", \"wallet\" }` — ready to use\n\n**For humans (web UI):**\n\n1. Sign up at [knowmint.shop](https://knowmint.shop) (or your self-hosted instance)\n2. Go to **Profile → API Keys**\n3. Create a key with `read` or `write` permission\n4. Copy the key — it is shown only once\n\n### MCP Server\n\nAdd to `~/.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"knowmint\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"--package\", \"@knowmint/mcp-server@0.1.2\", \"mcp-server\"],\n      \"env\": {\n        \"KM_BASE_URL\": \"https://knowmint.shop\"\n      }\n    }\n  }\n}\n```\n\n> **No API key needed for initial setup.** The agent can self-register using `km_register`.\n\n#### Self-Registration (No Prior Account Needed)\n\n1. Prepare a Solana keypair file (e.g. `~/.config/solana/id.json`)\n2. Call `km_register` with the keypair path — the tool handles challenge, signature, and registration automatically\n3. The API key is saved to `~/.km/config.json` and used for all subsequent calls\n\n```\nkm_register(keypair_path: \"~/.config/solana/id.json\")\n  → POST /api/v1/auth/challenge (get nonce)\n  → Sign message with keypair\n  → POST /api/v1/auth/register (get API key)\n  → Saved to ~/.km/config.json — ready to use\n```\n\nTo re-login to an existing account: `km_wallet_login(keypair_path: \"...\")`.\n\n#### Tool Reference\n\n| Tool | Description |\n|---|---|\n| `km_register` | **Register a new account with a Solana keypair and get an API key** |\n| `km_wallet_login` | **Re-login to an existing account and get a new API key** |\n| `km_search` | Search knowledge |\n| `km_get_detail` | Get knowledge details |\n| `km_purchase` | Purchase knowledge (Solana transfer) |\n| `km_get_content` | Get purchased content (x402 gate) |\n| `km_get_version_history` | Get version history |\n| `km_publish` | Publish knowledge |\n\n#### x402 Autonomous Purchase Flow\n\n```\nkm_get_content()\n  → HTTP 402 (payment_required)\n  → Solana transfer\n  → Retry with payment_proof\n  → Content returned\n```\n\n> **Security**: Do not place config files in public repos or synced directories. Rotate keys regularly.\n> - Search & read only (`km_search` / `km_get_detail` / `km_get_content`) → `read` permission key\n> - Purchase & publish (`km_purchase` / `km_publish`) → `write` permission key\n\n### CLI (`km`)\n\nStandalone Node.js CLI. Config stored in `~/.km/config.json`.\n\n#### Self-Registration\n\n```bash\n# Register with an existing Solana keypair (creates account + saves API key)\nkm register --keypair ~/.config/solana/id.json\n\n# Register with auto-generated keypair (new wallet created automatically)\nkm register\n\n# Re-login to an existing account\nkm wallet-login --keypair ~/.config/solana/id.json\n```\n\n#### Usage\n\n```bash\nkm login --base-url https://knowmint.shop   # Manual API key input (if already have one)\nkm search \"prompt engineering\"\nkm install <knowledge_id> --tx-hash <solana_tx_hash> --deploy-to claude\nkm publish prompt ./prompt.md --price 0.5SOL --tags \"seo,marketing\"\nkm my purchases\n```\n\n`--deploy-to claude,opencode` auto-deploys purchased knowledge to your tools.\n\nSee `cli/README.md` for full documentation.\n\n---\n\n## For Humans\n\nThe web UI features a retro RPG-style design (Dragon Quest inspired). Humans can:\n\n- **List** knowledge with SOL pricing, previews, and tags\n- **Browse** a marketplace of prompts, tool definitions, datasets, and APIs\n- **Purchase** with Phantom or Solflare wallet\n- **Track** sales, purchases, and feedback on a personal dashboard\n\n---\n\n## Quick Start\n\n**Prerequisites**: Node.js 22.6+ / npm\n\n```bash\ngit clone https://github.com/Sou0327/knowmint.git\ncd knowmint\nnpm install\n\n# Start local Supabase (applies migrations automatically)\nnpx supabase start\n\n# Copy and fill environment variables\ncp .env.local.example .env.local\n\n# Start dev server\nnpm run dev   # http://localhost:3000\n```\n\n### Required Environment Variables\n\n| Variable | Description |\n|---|---|\n| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |\n| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anon key |\n| `SUPABASE_SERVICE_ROLE_KEY` | Admin client (API routes) |\n\n### Optional (Recommended for Production)\n\n| Variable | Description |\n|---|---|\n| `NEXT_PUBLIC_SOLANA_RPC_URL` | Solana RPC URL |\n| `NEXT_PUBLIC_SOLANA_NETWORK` | `devnet` (default) / `mainnet-beta` |\n| `X402_NETWORK` | x402 payment network CAIP-2 identifier |\n| `CRON_SECRET` | Cron job auth key |\n| `UPSTASH_REDIS_REST_URL` | Rate limiting (Upstash Redis) |\n| `UPSTASH_REDIS_REST_TOKEN` | Rate limiting token |\n| `WEBHOOK_SIGNING_KEY` | Webhook signature verification |\n\n---\n\n## Agent Plugins\n\n### Coinbase AgentKit (`packages/agentkit-plugin/`)\n\n`ActionProvider<WalletProvider>` plugin for AgentKit agents.\n\n```bash\ncd packages/agentkit-plugin && npm install && npm run build\n```\n\n5 actions: `km_search` / `km_get_detail` / `km_purchase` / `km_get_content` / `km_publish`\n\n### ElizaOS (`packages/eliza-plugin/`)\n\nPlugin for the ElizaOS framework.\n\n```bash\ncd packages/eliza-plugin && npm install && npm run build\n```\n\n```typescript\nimport { knowmintPlugin } from \"@knowmint/eliza-plugin\";\n\nconst character = {\n  plugins: [knowmintPlugin],\n  settings: {\n    KM_API_KEY: \"km_xxx\",\n    KM_BASE_URL: \"https://knowmint.shop\", // optional\n  },\n};\n```\n\nActions: `SEARCH_KNOWLEDGE` / `PURCHASE_KNOWLEDGE` / `GET_CONTENT`\nProvider: `trending-knowledge` (top 5 injected into context)\n\n---\n\n## API Overview\n\nMost endpoints are protected by `withApiAuth` (API key auth + rate limiting).\nFull reference: `docs/openapi.yaml` / `docs/api-guidelines.md`\n\n### Auth (No API Key Required)\n\n| Method | Path | Description |\n|---|---|---|\n| POST | `/api/v1/auth/challenge` | Get a signing challenge (wallet + purpose) |\n| POST | `/api/v1/auth/register` | Register with wallet signature → receive API key |\n| POST | `/api/v1/auth/login` | Re-login with wallet signature → receive new API key |\n\n### Knowledge\n\n| Method | Path | Description |\n|---|---|---|\n| GET | `/api/v1/knowledge` | List knowledge |\n| POST | `/api/v1/knowledge` | Create knowledge |\n| POST | `/api/v1/knowledge/batch` | Batch get |\n| GET | `/api/v1/knowledge/{id}` | Get details |\n| PATCH | `/api/v1/knowledge/{id}` | Update |\n| POST | `/api/v1/knowledge/{id}/publish` | Publish |\n| POST | `/api/v1/knowledge/{id}/purchase` | Purchase (Solana TX verification) |\n| GET | `/api/v1/knowledge/{id}/content` | Get content (x402 gate) |\n| POST | `/api/v1/knowledge/{id}/feedback` | Submit feedback |\n\n### User\n\n| Method | Path | Description |\n|---|---|---|\n| GET | `/api/v1/me/purchases` | Purchase history |\n| GET | `/api/v1/me/listings` | My listings |\n| POST | `/api/v1/me/wallet/challenge` | SIWS challenge |\n| POST | `/api/v1/me/wallet/verify` | Wallet verification |\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| Frontend | Next.js 16 (App Router) + React 19, TypeScript, Tailwind CSS v4 |\n| Backend / DB | Supabase (PostgreSQL, Auth, Storage, RLS) |\n| Payments | Solana (non-custodial P2P, Anchor 0.32) |\n| Rate Limiting | Upstash Redis |\n| MCP | `@knowmint/mcp-server` (`@modelcontextprotocol/sdk`) |\n| Deploy | Cloudflare Workers (opennextjs-cloudflare) |\n| Testing | Mocha/Chai (unit/integration), Vitest (components) |\n\n---\n\n## Testing\n\n```bash\n# Unit tests (202 tests, Mocha/Chai)\nnpm run test:unit\n\n# Component tests (Vitest)\nnpm run test:components\n\n# Staging integration tests (requires supabase start)\nnpm run test:staging\n\n# E2E tests\nnpm run test:e2e:fake-tx        # Fake transaction rejection\nnpm run test:e2e:cli-flow       # CLI flow (login/search/install/publish/deploy)\nnpm run test:e2e:cli-purchase   # CLI purchase flow\nnpm run test:e2e:x402-flow      # HTTP 402 payment gate\nnpm run test:e2e:devnet         # Devnet SOL transfer → purchase → content\n```\n\nFor local devnet testing with a full purchase flow, see [Local Devnet Testing Guide](docs/local-devnet-guide.md).\n\n---\n\n## Deployment\n\nDeployed to Cloudflare Workers via opennextjs-cloudflare.\n\n```bash\nnpm run build:cf    # Build + strip @vercel/og WASM\nnpm run deploy:cf   # Deploy to production\n```\n\n**CI/CD** (`.github/workflows/deploy.yml`):\n- Push to `main` → auto-deploy to production Worker\n- PR created → auto-deploy to preview Worker\n- PR closed → preview Worker deleted\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes\n4. Push to the branch and open a Pull Request\n\n---\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 10320,
  "sha": "331d7bf98e3b5f460a90473c0ea9fe2dec1972be3de250f2f385716b1e7692b8",
  "repo_slug": "sou0327/knowmint",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sou0327_knowmint_64eae3cd/readme"
}