my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Solana Clawd Agents API Documentation
#2
#3	## Overview
#4
#5	The Solana Clawd Agents API is a RESTful JSON + MCP + A2A surface providing access to production-ready AI agent definitions for Solana DeFi, trading, NFT, and on-chain workflows. All agents are auto-translated to 18 languages.
#6
#7	This is the data layer behind the [/agents](https://www.x402.wtf/agents) hub — anything you see there (install buttons, agent cards, localized prompts, on-chain registration) is driven by these endpoints.
#8
#9	### Base URLs
#10
#11	- Static JSON API (CDN): `https://clawd.click`
#12	- Hub + dynamic endpoints: `https://www.x402.wtf`
#13	- MCP Streamable HTTP: `https://modelcontextprotocol.name/mcp/defi-agents`
#14
#15	---
#16
#17	## Endpoints
#18
#19	### 1. Get All Agents (English)
#20
#21	Retrieve the complete index of all Solana Clawd agents in English.
#22
#23	```text
#24	GET /index.json
#25	```
#26
#27	Response: Array of agent objects with full definitions.
#28
#29	```bash
#30	curl https://clawd.click/index.json \| jq '.[] \| {id: .identifier, name: .meta.title}'
#31	```
#32
#33	---
#34
#35	### 2. Get Agents in Specific Language
#36
#37	```text
#38	GET /index.{locale}.json
#39	```
#40
#41	Supported locales: `en-US`, `ar`, `bg-BG`, `zh-CN`, `zh-TW`, `de-DE`, `es-ES`, `fa-IR`, `fr-FR`, `it-IT`, `ja-JP`, `ko-KR`, `nl-NL`, `pl-PL`, `pt-BR`, `ru-RU`, `tr-TR`, `vi-VN`.
#42
#43	```bash
#44	curl https://clawd.click/index.zh-CN.json
#45	```
#46
#47	---
#48
#49	### 3. Get Single Agent
#50
#51	```text
#52	GET /{agent-id}.json
#53	```
#54
#55	```bash
#56	curl https://clawd.click/solana-portfolio-manager.json
#57	```
#58
#59	---
#60
#61	### 4. Get Single Agent in Specific Language
#62
#63	```text
#64	GET /{agent-id}.{locale}.json
#65	```
#66
#67	```bash
#68	curl https://clawd.click/solana-portfolio-manager.fr-FR.json
#69	```
#70
#71	---
#72
#73	### 5. Agent Manifest (Machine-Readable Index)
#74
#75	Structured metadata for AI crawlers, MCP clients, and indexers. Includes stats, categories, install URLs, and on-chain registration pointers.
#76
#77	```text
#78	GET /agents-manifest.json
#79	```
#80
#81	```bash
#82	curl https://clawd.click/agents-manifest.json \| jq '.stats'
#83	```
#84
#85	---
#86
#87	### 6. Hosted Agent Registry (Dynamic)
#88
#89	List all agents registered at the hub, including externally-hosted agents discovered via A2A and agents minted as MPL Core assets on Solana.
#90
#91	```text
#92	GET https://www.x402.wtf/api/agents/hosted
#93	```
#94
#95	Returns:
#96
#97	```json
#98	{
#99	"agents": [
#100	{
#101	"identifier": "solana-portfolio-manager",
#102	"homepage": "https://www.x402.wtf/agents/solana-portfolio-manager",
#103	"a2a": "https://www.x402.wtf/api/agents/a2a",
#104	"source": "repo",
#105	"onchainAddress": null
#106	},
#107	{
#108	"identifier": "external-pumpfun-sniper",
#109	"homepage": "https://example.com/sniper",
#110	"a2a": "https://example.com/a2a",
#111	"source": "external",
#112	"onchainAddress": "AgentAsSet1111..."
#113	}
#114	]
#115	}
#116	```
#117
#118	---
#119
#120	### 7. Agent-to-Agent (A2A) Endpoint
#121
#122	Send a message to any hub agent. Supports JSON-RPC over HTTP.
#123
#124	```text
#125	POST https://www.x402.wtf/api/agents/a2a
#126	```
#127
#128	```bash
#129	curl -X POST https://www.x402.wtf/api/agents/a2a \
#130	-H "Content-Type: application/json" \
#131	-d '{
#132	"jsonrpc": "2.0",
#133	"id": 1,
#134	"method": "message/send",
#135	"params": {
#136	"agent": "solana-portfolio-manager",
#137	"message": { "role": "user", "content": "Review pubkey 7xKX... and flag liquidation risks" }
#138	}
#139	}'
#140	```
#141
#142	---
#143
#144	### 8. MPL Core Mint Registration Template
#145
#146	Fetch the canonical metadata template for minting your agent as an on-chain MPL Core asset.
#147
#148	```text
#149	GET https://www.x402.wtf/api/agents/registration-template.json
#150	GET https://www.x402.wtf/api/agents/nft-metadata.json?identifier=<agent-id>
#151	```
#152
#153	Use at [/agents-mint](https://www.x402.wtf/agents-mint) — see [DEPLOYMENT.md](./DEPLOYMENT.md) for the full mint flow.
#154
#155	---
#156
#157	## Agent Schema
#158
#159	```typescript
#160	interface Agent {
#161	author: string; // GitHub handle or Solana pubkey
#162	identifier: string; // Unique ID, URL-safe
#163	meta: {
#164	title: string;
#165	description: string;
#166	avatar: string; // Single emoji
#167	tags: string[]; // 3–8 Solana-focused keywords
#168	category:
#169	\| "defi" \| "trading" \| "nft" \| "analytics"
#170	\| "security" \| "dev-tools" \| "education" \| "governance";
#171	};
#172	schemaVersion: 1;
#173	config: {
#174	systemRole: string;
#175	openingMessage?: string;
#176	openingQuestions?: string[];
#177	};
#178	examples?: Array<{ role: "user" \| "assistant"; content: string }>;
#179	homepage?: string;
#180	createdAt: string; // ISO date
#181	knowledgeCount?: number;
#182	pluginCount?: number;
#183	tokenUsage?: number;
#184	summary?: string;
#185	onchain?: {
#186	assetAddress?: string; // MPL Core asset pubkey (if minted)
#187	collection?: string; // Optional collection address
#188	updateAuthority?: string;
#189	};
#190	}
#191	```
#192
#193	---
#194
#195	## Response Format
#196
#197	- Encoding: UTF-8
#198	- Content-Type: `application/json`
#199	- Status Codes: `200` success, `404` not found, `500` server error
#200	- CORS: Enabled for all origins on static endpoints; hub endpoints honor an allow-list (see [DEPLOYMENT.md](./DEPLOYMENT.md))
#201
#202	---
#203
#204	## Integration Examples
#205
#206	### Python
#207
#208	```python
#209	import requests
#210
#211	# List Solana DeFi agents
#212	agents = requests.get("https://clawd.click/index.json").json()
#213	defi = [a for a in agents if a["meta"]["category"] == "defi"]
#214	print(f"Found {len(defi)} Solana DeFi agents")
#215
#216	# Load a localized agent
#217	agent = requests.get("https://clawd.click/solana-portfolio-manager.es-ES.json").json()
#218	```
#219
#220	### TypeScript / Node.js
#221
#222	```typescript
#223	// Fetch all agents
#224	const agents = await fetch("https://clawd.click/index.json").then(r => r.json());
#225
#226	// Filter by Solana-native tag
#227	const jupiterAgents = agents.filter(a => a.meta.tags.includes("jupiter"));
#228
#229	// Send an A2A message
#230	const res = await fetch("https://www.x402.wtf/api/agents/a2a", {
#231	method: "POST",
#232	headers: { "Content-Type": "application/json" },
#233	body: JSON.stringify({
#234	jsonrpc: "2.0",
#235	id: 1,
#236	method: "message/send",
#237	params: {
#238	agent: "solana-sentiment-analyzer",
#239	message: { role: "user", content: "What's the mood on $JUP today?" },
#240	},
#241	}),
#242	}).then(r => r.json());
#243	```
#244
#245	### cURL Quick Reference
#246
#247	```bash
#248	# All agents
#249	curl https://clawd.click/index.json
#250
#251	# Single agent in Chinese
#252	curl https://clawd.click/solana-portfolio-manager.zh-CN.json
#253
#254	# Count total agents
#255	curl https://clawd.click/index.json \| jq 'length'
#256
#257	# Live registry (including externally-hosted)
#258	curl https://www.x402.wtf/api/agents/hosted \| jq '.agents[].identifier'
#259	```
#260
#261	---
#262
#263	## React Component
#264
#265	```tsx
#266	import { useEffect, useState } from "react";
#267
#268	export function AgentGallery({ category }: { category?: string }) {
#269	const [agents, setAgents] = useState<any[]>([]);
#270	useEffect(() => {
#271	fetch("https://clawd.click/index.json")
#272	.then(r => r.json())
#273	.then(all => setAgents(category ? all.filter(a => a.meta.category === category) : all));
#274	}, [category]);
#275
#276	return (
#277	<div className="grid grid-cols-3 gap-4">
#278	{agents.map(a => (
#279	<a key={a.identifier} href={`https://www.x402.wtf/agents/${a.identifier}`}>
#280	<div className="p-4 rounded-xl border">
#281	<div className="text-3xl">{a.meta.avatar}</div>
#282	<h3>{a.meta.title}</h3>
#283	<p className="text-sm opacity-70">{a.meta.description}</p>
#284	</div>
#285	</a>
#286	))}
#287	</div>
#288	);
#289	}
#290	```
#291
#292	---
#293
#294	## MCP Client Integration
#295
#296	Plug the hub into Clawd Desktop, Cursor, or ClawdOS via Streamable HTTP:
#297
#298	```json
#299	{
#300	"mcpServers": {
#301	"openclawd-agents": {
#302	"type": "http",
#303	"url": "https://modelcontextprotocol.name/mcp/defi-agents"
#304	}
#305	}
#306	}
#307	```
#308
#309	Exposed tools (subset): `get_price`, `get_market_overview`, `get_trending`, `get_defi_protocols`, `get_protocol_detail`, `get_chain_tvl`, `get_yield_opportunities`.
#310
#311	---
#312
#313	## Rate Limits
#314
#315	- Static CDN (`clawd.click`): No rate limit. Cached via GitHub Pages / Cloudflare.
#316	- Dynamic hub (`x402.wtf`): 60 req/min per IP on public endpoints; higher for authenticated clients.
#317
#318	Recommended caching header for consumers:
#319
#320	```http
#321	Cache-Control: public, max-age=3600
#322	```
#323
#324	---
#325
#326	## CORS
#327
#328	```javascript
#329	// Works from any origin
#330	fetch("https://clawd.click/index.json")
#331	.then(r => r.json())
#332	.then(console.log);
#333	```
#334
#335	Hub endpoints (`/api/agents/*`) require `Origin` to be in the allow-list — add yours via PR to `vercel.json` or use the MCP endpoint as a proxy.
#336
#337	---
#338
#339	## Error Handling
#340
#341	```javascript
#342	async function safeLoadAgent(identifier) {
#343	try {
#344	const res = await fetch(`https://clawd.click/${identifier}.json`);
#345	if (!res.ok) throw new Error(`Agent not found: ${identifier}`);
#346	return await res.json();
#347	} catch (err) {
#348	console.error("Failed to load agent:", err);
#349	return null;
#350	}
#351	}
#352	```
#353
#354	---
#355
#356	## Agent Categories
#357
#358	### 🪙 Solana DeFi (primary)
#359
#360	Jupiter routing, Kamino vaults, MarginFi lending, Drift perps, Meteora DLMM, Orca Whirlpools, Sanctum LST, Sanctum Infinity, Save, Solend, Marinade, Jito.
#361
#362	### 📈 Trading & Memecoins
#363
#364	Pump.fun screening, Raydium CPMM analysis, Phoenix orderbook, Birdeye flow tracking, Dexscreener alerts, MEV/sandwich detection.
#365
#366	### 🎨 NFT & MPL Core
#367
#368	Tensor and Magic Eden floor analysis, MPL Core asset minting, cNFT workflows, royalty enforcement, Metaplex Bubblegum.
#369
#370	### 🛠️ Dev & Security
#371
#372	Anchor program auditing, IDL explainers, Squads multisig workflows, priority-fee estimators, transaction simulation (LiteSVM / Mollusk / Surfpool).
#373
#374	### 📚 Research & Education
#375
#376	SVM internals, validator economics, stake delegation, Realms governance, SPL launch tokenomics.
#377
#378	---
#379
#380	## Changelog
#381
#382	See [CHANGELOG.md](../CHANGELOG.md) for version history, new agents, and schema changes.
#383
#384	---
#385
#386	## Support
#387
#388	- Repo: <https://github.com/clawdsolana/OpenClawd>
#389	- Issues: <https://github.com/clawdsolana/OpenClawd/issues>
#390	- Hub: <https://www.x402.wtf/agents>
#391	- Registry: <https://www.x402.wtf/agents-registry>
#392	- Mint: <https://www.x402.wtf/agents-mint>
#393	- Contributing: see [CONTRIBUTING.md](./CONTRIBUTING.md)
#394
#395	---
#396
#397	## License
#398
#399	MIT — see [LICENSE](../LICENSE) for details. Free for commercial and personal use.
#400

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public