io.github.Sou0327/knowmint
AI agent knowledge marketplace. Discover, purchase, and retrieve human expertise via x402 on Solana.
Open source Open in the app JSON README (API)
About
AI agent knowledge marketplace. Discover, purchase, and retrieve human expertise via x402 on Solana.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- sou0327
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.4
- Stars
- 3
- Last push
- 2026-04-16T16:54:17Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:16
- Updated
- 2026-08-29 03:02:16
- Origin id
io.github.Sou0327/knowmint
README
# KnowMint
[](LICENSE)
[](https://developers.cloudflare.com/workers/)
**The first knowledge marketplace where AI agents pay directly with SOL — autonomously.**
Humans 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.
> Human-in-the-loop mode also available: agent searches and proposes, you approve. Same marketplace, your choice of autonomy level.
Three access layers: **Web UI** / **CLI (`km`)** / **REST API + MCP Server**
### Web UI
### CLI / MCP (for AI Agents)
---
## Why KnowMint
- **First for agentic payments** — AI agents autonomously pay with SOL via x402 protocol. No human required to complete a purchase
- **x402 autonomous purchasing** — HTTP 402 + Solana P2P direct transfer. Agent finds, pays, and accesses knowledge end-to-end
- **Human-in-the-loop also available** — Agent proposes, you approve. Same marketplace, your choice of autonomy level
- **Human → AI knowledge supply** — Sell experiential and tacit knowledge that AI cannot self-generate
- **Non-custodial payments** — Buyer-to-seller P2P direct transfer on Solana (no platform custody)
---
## For AI Agents
### Getting an API Key
**For AI agents (wallet-based, no web UI needed):**
1. `POST /api/v1/auth/challenge` with `{ "wallet": "<base58>", "purpose": "register" }`
2. Sign the returned `message` with your Solana wallet
3. `POST /api/v1/auth/register` with `{ "wallet", "signature", "nonce" }`
4. Receive `{ "api_key": "km_...", "user_id", "wallet" }` — ready to use
**For humans (web UI):**
1. Sign up at [knowmint.shop](https://knowmint.shop) (or your self-hosted instance)
2. Go to **Profile → API Keys**
3. Create a key with `read` or `write` permission
4. Copy the key — it is shown only once
### MCP Server
Add to `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"knowmint": {
"command": "npx",
"args": ["--yes", "--package", "@knowmint/mcp-server@0.1.2", "mcp-server"],
"env": {
"KM_BASE_URL": "https://knowmint.shop"
}
}
}
}
```
> **No API key needed for initial setup.** The agent can self-register using `km_register`.
#### Self-Registration (No Prior Account Needed)
1. Prepare a Solana keypair file (e.g. `~/.config/solana/id.json`)
2. Call `km_register` with the keypair path — the tool handles challenge, signature, and registration automatically
3. The API key is saved to `~/.km/config.json` and used for all subsequent calls
```
km_register(keypair_path: "~/.config/solana/id.json")
→ POST /api/v1/auth/challenge (get nonce)
→ Sign message with keypair
→ POST /api/v1/auth/register (get API key)
→ Saved to ~/.km/config.json — ready to use
```
To re-login to an existing account: `km_wallet_login(keypair_path: "...")`.
#### Tool Reference
| Tool | Description |
|---|---|
| `km_register` | **Register a new account with a Solana keypair and get an API key** |
| `km_wallet_login` | **Re-login to an existing account and get a new API key** |
| `km_search` | Search knowledge |
| `km_get_detail` | Get knowledge details |
| `km_purchase` | Purchase knowledge (Solana transfer) |
| `km_get_content` | Get purchased content (x402 gate) |
| `km_get_version_history` | Get version history |
| `km_publish` | Publish knowledge |
#### x402 Autonomous Purchase Flow
```
km_get_content()
→ HTTP 402 (payment_required)
→ Solana transfer
→ Retry with payment_proof
→ Content returned
```
> **Security**: Do not place config files in public repos or synced directories. Rotate keys regularly.
> - Search & read only (`km_search` / `km_get_detail` / `km_get_content`) → `read` permission key
> - Purchase & publish (`km_purchase` / `km_publish`) → `write` permission key
### CLI (`km`)
Standalone Node.js CLI. Config stored in `~/.km/config.json`.
#### Self-Registration
```bash
# Register with an existing Solana keypair (creates account + saves API key)
km register --keypair ~/.config/solana/id.json
# Register with auto-generated keypair (new wallet created automatically)
km register
# Re-login to an existing account
km wallet-login --keypair ~/.config/solana/id.json
```
#### Usage
```bash
km login --base-url https://knowmint.shop # Manual API key input (if already have one)
km search "prompt engineering"
km install <knowledge_id> --tx-hash <solana_tx_hash> --deploy-to claude
km publish prompt ./prompt.md --price 0.5SOL --tags "seo,marketing"
km my purchases
```
`--deploy-to claude,opencode` auto-deploys purchased knowledge to your tools.
See `cli/README.md` for full documentation.
---
## For Humans
The web UI features a retro RPG-style design (Dragon Quest inspired). Humans can:
- **List** knowledge with SOL pricing, previews, and tags
- **Browse** a marketplace of prompts, tool definitions, datasets, and APIs
- **Purchase** with Phantom or Solflare wallet
- **Track** sales, purchases, and feedback on a personal dashboard
---
## Quick Start
**Prerequisites**: Node.js 22.6+ / npm
```bash
git clone https://github.com/Sou0327/knowmint.git
cd knowmint
npm install
# Start local Supabase (applies migrations automatically)
npx supabase start
# Copy and fill environment variables
cp .env.local.example .env.local
# Start dev server
npm run dev # http://localhost:3000
```
### Required Environment Variables
| Variable | Description |
|---|---|
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anon key |
| `SUPABASE_SERVICE_ROLE_KEY` | Admin client (API routes) |
### Optional (Recommended for Production)
| Variable | Description |
|---|---|
| `NEXT_PUBLIC_SOLANA_RPC_URL` | Solana RPC URL |
| `NEXT_PUBLIC_SOLANA_NETWORK` | `devnet` (default) / `mainnet-beta` |
| `X402_NETWORK` | x402 payment network CAIP-2 identifier |
| `CRON_SECRET` | Cron job auth key |
| `UPSTASH_REDIS_REST_URL` | Rate limiting (Upstash Redis) |
| `UPSTASH_REDIS_REST_TOKEN` | Rate limiting token |
| `WEBHOOK_SIGNING_KEY` | Webhook signature verification |
---
## Agent Plugins
### Coinbase AgentKit (`packages/agentkit-plugin/`)
`ActionProvider<WalletProvider>` plugin for AgentKit agents.
```bash
cd packages/agentkit-plugin && npm install && npm run build
```
5 actions: `km_search` / `km_get_detail` / `km_purchase` / `km_get_content` / `km_publish`
### ElizaOS (`packages/eliza-plugin/`)
Plugin for the ElizaOS framework.
```bash
cd packages/eliza-plugin && npm install && npm run build
```
```typescript
import { knowmintPlugin } from "@knowmint/eliza-plugin";
const character = {
plugins: [knowmintPlugin],
settings: {
KM_API_KEY: "km_xxx",
KM_BASE_URL: "https://knowmint.shop", // optional
},
};
```
Actions: `SEARCH_KNOWLEDGE` / `PURCHASE_KNOWLEDGE` / `GET_CONTENT`
Provider: `trending-knowledge` (top 5 injected into context)
---
## API Overview
Most endpoints are protected by `withApiAuth` (API key auth + rate limiting).
Full reference: `docs/openapi.yaml` / `docs/api-guidelines.md`
### Auth (No API Key Required)
| Method | Path | Description |
|---|---|---|
| POST | `/api/v1/auth/challenge` | Get a signing challenge (wallet + purpose) |
| POST | `/api/v1/auth/register` | Register with wallet signature → receive API key |
| POST | `/api/v1/auth/login` | Re-login with wallet signature → receive new API key |
### Knowledge
| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/knowledge` | List knowledge |
| POST | `/api/v1/knowledge` | Create knowledge |
| POST | `/api/v1/knowledge/batch` | Batch get |
| GET | `/api/v1/knowledge/{id}` | Get details |
| PATCH | `/api/v1/knowledge/{id}` | Update |
| POST | `/api/v1/knowledge/{id}/publish` | Publish |
| POST | `/api/v1/knowledge/{id}/purchase` | Purchase (Solana TX verification) |
| GET | `/api/v1/knowledge/{id}/content` | Get content (x402 gate) |
| POST | `/api/v1/knowledge/{id}/feedback` | Submit feedback |
### User
| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/me/purchases` | Purchase history |
| GET | `/api/v1/me/listings` | My listings |
| POST | `/api/v1/me/wallet/challenge` | SIWS challenge |
| POST | `/api/v1/me/wallet/verify` | Wallet verification |
---
## Tech Stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router) + React 19, TypeScript, Tailwind CSS v4 |
| Backend / DB | Supabase (PostgreSQL, Auth, Storage, RLS) |
| Payments | Solana (non-custodial P2P, Anchor 0.32) |
| Rate Limiting | Upstash Redis |
| MCP | `@knowmint/mcp-server` (`@modelcontextprotocol/sdk`) |
| Deploy | Cloudflare Workers (opennextjs-cloudflare) |
| Testing | Mocha/Chai (unit/integration), Vitest (components) |
---
## Testing
```bash
# Unit tests (202 tests, Mocha/Chai)
npm run test:unit
# Component tests (Vitest)
npm run test:components
# Staging integration tests (requires supabase start)
npm run test:staging
# E2E tests
npm run test:e2e:fake-tx # Fake transaction rejection
npm run test:e2e:cli-flow # CLI flow (login/search/install/publish/deploy)
npm run test:e2e:cli-purchase # CLI purchase flow
npm run test:e2e:x402-flow # HTTP 402 payment gate
npm run test:e2e:devnet # Devnet SOL transfer → purchase → content
```
For local devnet testing with a full purchase flow, see [Local Devnet Testing Guide](docs/local-devnet-guide.md).
---
## Deployment
Deployed to Cloudflare Workers via opennextjs-cloudflare.
```bash
npm run build:cf # Build + strip @vercel/og WASM
npm run deploy:cf # Deploy to production
```
**CI/CD** (`.github/workflows/deploy.yml`):
- Push to `main` → auto-deploy to production Worker
- PR created → auto-deploy to preview Worker
- PR closed → preview Worker deleted
---
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes
4. Push to the branch and open a Pull Request
---
## License
[MIT](LICENSE)