my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	# AI Agent API - Cloudflare Workers
#2
#3	Production-ready API for AI agent authentication and Solana wallet management, deployed on Cloudflare's edge network.
#4
#5	## Features
#6
#7	- Agent Registration - Create AI agents with unique API keys
#8	- Session Authentication - JWT-like session tokens for secure access
#9	- Crossmint Wallets - Non-custodial Solana wallets via MPC
#10	- Rate Limiting - Per-agent request limits with KV storage
#11	- Activity Logging - Full audit trail of all operations
#12	- Global Edge Deployment - Low latency worldwide
#13
#14	## Quick Start
#15
#16	### 1. Prerequisites
#17
#18	```bash
#19	# Install Wrangler CLI
#20	npm install -g wrangler
#21
#22	# Login to Cloudflare
#23	wrangler login
#24	```
#25
#26	### 2. Install Dependencies
#27
#28	```bash
#29	cd cloudflare-agent-api
#30	npm install
#31	```
#32
#33	### 3. Verify or Create D1 Database
#34
#35	```bash
#36	# Check whether agent-db already exists
#37	wrangler d1 list
#38
#39	# Only create it if it is not already listed
#40	wrangler d1 create agent-db
#41
#42	# You'll get output like:
#43	# [[d1_databases]]
#44	# binding = "DB"
#45	# database_name = "agent-db"
#46	# database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
#47
#48	# Copy the database_id to wrangler.toml
#49	```
#50
#51	### 4. Create KV Namespaces
#52
#53	```bash
#54	# Create Sessions KV
#55	wrangler kv namespace create SESSIONS
#56
#57	# Create Rate Limits KV
#58	wrangler kv namespace create RATE_LIMITS
#59
#60	# Copy the IDs to wrangler.toml
#61	```
#62
#63	Wrangler 4 uses `wrangler kv namespace ...`. The old `wrangler kv:namespace ...`
#64	form is no longer accepted.
#65
#66	### 5. Update wrangler.toml
#67
#68	Replace the placeholder IDs with your actual IDs:
#69
#70	```toml
#71	[[d1_databases]]
#72	binding = "DB"
#73	database_name = "agent-db"
#74	database_id = "YOUR_ACTUAL_DATABASE_ID"
#75
#76	[[kv_namespaces]]
#77	binding = "SESSIONS"
#78	id = "YOUR_ACTUAL_SESSIONS_KV_ID"
#79
#80	[[kv_namespaces]]
#81	binding = "RATE_LIMITS"
#82	id = "YOUR_ACTUAL_RATE_LIMITS_KV_ID"
#83	```
#84
#85	### 6. Run Database Migration
#86
#87	```bash
#88	# Apply schema to the remote production D1 database
#89	wrangler d1 execute agent-db --remote --file=./schema.sql
#90
#91	# For local development only
#92	wrangler d1 execute agent-db --local --file=./schema.sql
#93	```
#94
#95	### 7. Set Secrets
#96
#97	```bash
#98	# Set Crossmint API key
#99	wrangler secret put CROSSMINT_SERVERSIDE_API_KEY
#100	# Enter: sk_staging_your-key-here (or sk_production_xxx for mainnet)
#101
#102	# Optional: Client-side key
#103	wrangler secret put CROSSMINT_CLIENTSIDE_API_KEY
#104	```
#105
#106	### 8. Deploy
#107
#108	```bash
#109	# Deploy to production
#110	wrangler deploy
#111
#112	# Or deploy to staging
#113	wrangler deploy --env staging
#114	```
#115
#116	### 9. Test Your API
#117
#118	```bash
#119	# Health check
#120	curl https://agent-api.YOUR_SUBDOMAIN.workers.dev/health
#121
#122	# Register an agent
#123	curl -X POST https://agent-api.YOUR_SUBDOMAIN.workers.dev/api/agents/register \
#124	-H "Content-Type: application/json" \
#125	-d '{"name": "My Trading Bot", "description": "Automated trading agent"}'
#126	```
#127
#128	## API Endpoints
#129
#130	### Public Endpoints
#131
#132	\| Method \| Endpoint \| Description \|
#133	\|--------\|----------\|-------------\|
#134	\| GET \| `/health` \| Health check \|
#135	\| GET \| `/api/agents/info` \| API information \|
#136	\| POST \| `/api/agents/register` \| Register new agent \|
#137	\| POST \| `/api/agents/login` \| Login with API key \|
#138
#139	### Protected Endpoints (Require Authentication)
#140
#141	\| Method \| Endpoint \| Description \|
#142	\|--------\|----------\|-------------\|
#143	\| GET \| `/api/agents/me` \| Get agent info \|
#144	\| POST \| `/api/agents/logout` \| Invalidate session \|
#145	\| POST \| `/api/agents/wallet/create` \| Create Solana wallet \|
#146	\| GET \| `/api/agents/wallet` \| Get wallet & balances \|
#147	\| POST \| `/api/agents/wallet/fund` \| Fund wallet (devnet) \|
#148	\| POST \| `/api/agents/wallet/transfer` \| Transfer tokens \|
#149	\| GET \| `/api/agents/rate-limit` \| Check rate limit \|
#150	\| POST \| `/api/agents/api-key/regenerate` \| Regenerate API key \|
#151
#152	## Authentication
#153
#154	### Method 1: API Key (Stateless)
#155
#156	```bash
#157	curl -X GET https://agent-api.YOUR_SUBDOMAIN.workers.dev/api/agents/me \
#158	-H "X-Agent-API-Key: agent_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
#159	```
#160
#161	### Method 2: Session Token (After Login)
#162
#163	```bash
#164	# Login to get session token
#165	curl -X POST https://agent-api.YOUR_SUBDOMAIN.workers.dev/api/agents/login \
#166	-H "Content-Type: application/json" \
#167	-d '{"apiKey": "agent_xxx..."}'
#168
#169	# Use session token
#170	curl -X GET https://agent-api.YOUR_SUBDOMAIN.workers.dev/api/agents/me \
#171	-H "X-Agent-Session: agent_yyy..."
#172	```
#173
#174	## Example Workflow
#175
#176	```javascript
#177	// 1. Register a new agent
#178	const registerRes = await fetch('https://agent-api.example.workers.dev/api/agents/register', {
#179	method: 'POST',
#180	headers: { 'Content-Type': 'application/json' },
#181	body: JSON.stringify({
#182	name: 'Trading Bot Alpha',
#183	description: 'Automated DeFi trading agent',
#184	chain: 'solana-devnet'
#185	})
#186	});
#187	const { data } = await registerRes.json();
#188	const apiKey = data.apiKey; // SAVE THIS!
#189
#190	// 2. Login to get session
#191	const loginRes = await fetch('https://agent-api.example.workers.dev/api/agents/login', {
#192	method: 'POST',
#193	headers: { 'Content-Type': 'application/json' },
#194	body: JSON.stringify({ apiKey })
#195	});
#196	const { data: loginData } = await loginRes.json();
#197	const sessionToken = loginData.sessionToken;
#198
#199	// 3. Create wallet
#200	const walletRes = await fetch('https://agent-api.example.workers.dev/api/agents/wallet/create', {
#201	method: 'POST',
#202	headers: {
#203	'Content-Type': 'application/json',
#204	'X-Agent-Session': sessionToken
#205	}
#206	});
#207	const { data: walletData } = await walletRes.json();
#208	console.log('Wallet address:', walletData.wallet.address);
#209
#210	// 4. Fund wallet (devnet only)
#211	await fetch('https://agent-api.example.workers.dev/api/agents/wallet/fund', {
#212	method: 'POST',
#213	headers: {
#214	'Content-Type': 'application/json',
#215	'X-Agent-Session': sessionToken
#216	},
#217	body: JSON.stringify({ amount: 10 })
#218	});
#219
#220	// 5. Transfer tokens
#221	await fetch('https://agent-api.example.workers.dev/api/agents/wallet/transfer', {
#222	method: 'POST',
#223	headers: {
#224	'Content-Type': 'application/json',
#225	'X-Agent-Session': sessionToken
#226	},
#227	body: JSON.stringify({
#228	toAddress: 'RecipientAddress...',
#229	token: 'usdc',
#230	amount: '5.00'
#231	})
#232	});
#233	```
#234
#235	## Local Development
#236
#237	```bash
#238	# Start local dev server
#239	npm run dev
#240
#241	# The API will be available at http://localhost:8787
#242
#243	# Run migrations on local D1
#244	npm run db:migrate:local
#245	```
#246
#247	## OpenAI CUA Ralph Orchestrator + Steel (Node.js)
#248
#249	If you want browser-control agents (CUA) with OpenAI and Steel, use the ready starter in:
#250
#251	- `examples/steel-openai-ralph-cua/`
#252
#253	Quick run:
#254
#255	```bash
#256	cd examples/steel-openai-ralph-cua
#257	npm install
#258	cp .env.example .env
#259	# set STEEL_API_KEY and OPENAI_API_KEY in .env
#260	npm run dev
#261	```
#262
#263	This starter:
#264	- creates a Steel browser session,
#265	- captures screenshots,
#266	- runs a GPT-5.5 Ralph orchestrator action loop through OpenAI Responses,
#267	- translates normalized coordinates (0-1000) into Steel viewport pixels,
#268	- executes click/type/scroll/key/wait actions via Steel Computer API.
#269
#270	## Environment Variables
#271
#272	\| Variable \| Required \| Description \|
#273	\|----------\|----------\|-------------\|
#274	\| `CROSSMINT_SERVERSIDE_API_KEY` \| Yes \| Crossmint server-side API key \|
#275	\| `CROSSMINT_CLIENTSIDE_API_KEY` \| No \| Crossmint client-side API key \|
#276	\| `ENVIRONMENT` \| No \| `staging` or `production` \|
#277	\| `CORS_ORIGIN` \| No \| CORS allowed origin (default: `*`) \|
#278
#279	## Database Schema
#280
#281	The API uses Cloudflare D1 (SQLite) with the following tables:
#282
#283	- agents - Agent identities, API keys, permissions
#284	- sessions - Active session tokens
#285	- agent_activity - Audit log of all actions
#286	- transactions - Wallet transaction history
#287	- api_key_history - API key regeneration history
#288
#289	## Rate Limiting
#290
#291	Default limits per agent:
#292	- 30 requests per minute
#293	- 1000 requests per day
#294
#295	Rate limit data is stored in Cloudflare KV for fast edge access.
#296
#297	## Security
#298
#299	- API keys are SHA-256 hashed before storage
#300	- Session tokens expire after 24 hours
#301	- All wallet operations use Crossmint MPC (no private key exposure)
#302	- Request IP addresses are logged for audit
#303	- Rate limiting prevents abuse
#304
#305	## Monitoring
#306
#307	```bash
#308	# View real-time logs
#309	wrangler tail
#310
#311	# View logs for staging
#312	wrangler tail --env staging
#313	```
#314
#315	## Troubleshooting
#316
#317	### "Crossmint API not configured"
#318	Set your Crossmint API key:
#319	```bash
#320	wrangler secret put CROSSMINT_SERVERSIDE_API_KEY
#321	```
#322
#323	### "D1 database not found"
#324	Make sure the database exists and the ID in `wrangler.toml` matches:
#325	```bash
#326	wrangler d1 list
#327	```
#328
#329	If `agent-db` is already listed, do not create it again. Copy its UUID into the
#330	`database_id` field, then run:
#331
#332	```bash
#333	wrangler d1 execute agent-db --remote --file=./schema.sql
#334	```
#335
#336	### "Rate limit exceeded"
#337	Wait for the rate limit window to reset, or increase limits in the database:
#338	```sql
#339	UPDATE agents SET requests_per_minute = 60, requests_per_day = 5000 WHERE id = 'agt_xxx';
#340	```
#341
#342	## License
#343
#344	MIT
#345

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public