CAP-402 API Documentation

API Reference

Base URL: https://cap402.com | Authentication: X-API-Key header (optional)

Common Use Cases

I want to...	Endpoint	Example
Get token price	`POST /invoke`	`{"capability_id": "cap.price.lookup.v1", "inputs": {"base_token": "SOL"}}`
Swap tokens	`POST /invoke`	`{"capability_id": "cap.swap.execute.v1", "inputs": {"token_in": "SOL", "token_out": "USDC", "amount_in": 10}}`
Check MEV risk	`POST /mev/analyze`	`{"token_in": "SOL", "amount": 1000}`
Find arbitrage	`GET /alpha/arbitrage`	Returns live opportunities
Track whales	`GET /alpha/whale-tracker`	Returns recent large txs
List capabilities	`GET /capabilities`	Returns all 20+ capabilities
Private AI analysis	`POST /invoke`	`{"capability_id": "cap.ai.inference.v1", "inputs": {"model": "sentiment-analysis", "input": "text", "privacy_level": 2}}`
Private KYC proof	`POST /invoke`	`{"capability_id": "cap.zk.kyc.v1", "inputs": {"verification_type": "age", "public_inputs": {"min_age": 18}}}`

Common Error Codes

400Bad Request — Invalid parameters or malformed JSON
401Unauthorized — Missing or invalid API key for protected endpoints
404Not Found — Capability or resource doesn't exist
429Rate Limited — Too many requests (10/min anonymous, 200/min trusted)
500Internal Error — Server-side failure, retry with exponential backoff

Core Capabilities

POST /invoke Execute any capability by ID

Description

The primary endpoint for executing capabilities. Supports all 13 registered capabilities including price lookups, swaps, ZK proofs, FHE compute, and confidential operations.

Request Body

Parameter	Type	Required	Description
capability_id	string	required	Capability identifier (e.g., `cap.price.lookup.v1`)
inputs	object	required	Capability-specific input parameters
preferences	object	optional	Execution preferences: `privacy_level` (0-3), `max_cost`, `timeout_ms`

Example Request

curl -X POST https://cap402.com/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "capability_id": "cap.price.lookup.v1",
    "inputs": { "base_token": "SOL", "quote_token": "USDC" }
  }'

Response

{ "success": true, "capability_id": "cap.price.lookup.v1", "outputs": { "price": 185.42, "source": "jupiter", "timestamp": 1705347600000 }, "execution_time_ms": 45, "receipt": { "receipt_id": "rec_abc123", "signature": "0x..." } }

Errors

400Missing capability_id or inputs
404Capability not found
422Invalid inputs for capability schema

GET /capabilities List all registered capabilities

Description

Returns all 13 registered capabilities with their full schemas, input/output definitions, and sponsor information.

Query Parameters

Parameter	Type	Required	Description
category	string	optional	Filter by category: `price`, `wallet`, `swap`, `zk`, `fhe`
privacy_level	number	optional	Filter by minimum privacy level (0-3)

Example Request

curl https://cap402.com/capabilities

Response

{ "capabilities": [ { "id": "cap.price.lookup.v1", "name": "Price Lookup", "description": "Get real-time token prices", "sponsor": "helius", "execution": { "mode": "public" }, "inputs": { "base_token": "string" }, "outputs": { "price": "number" } } ], "total": 13 }

A2A Protocol

POST /a2a/invoke Agent-to-agent capability invocation

Description

Enables one agent to invoke a capability through another agent. Tracks reputation for both agents and supports privacy levels.

Request Body

Parameter	Type	Required	Description
from_agent	string	required	Source agent ID
to_agent	string	required	Target agent ID
capability_id	string	required	Capability to invoke
inputs	object	optional	Capability inputs
privacy_level	number	optional	0=public, 1=obscured, 2=encrypted, 3=zk

Example Request

curl -X POST https://cap402.com/a2a/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "from_agent": "trading-bot-alpha",
    "to_agent": "price-oracle",
    "capability_id": "cap.price.lookup.v1",
    "inputs": { "base_token": "SOL" }
  }'

Response

{ "success": true, "a2a_protocol": { "from": "trading-bot-alpha", "to": "price-oracle", "execution_time_ms": 164 }, "outputs": { "price": 185.42 }, "reputation_updated": true }

GET /a2a/discover/:capability_id Find agents that provide a capability

Description

Discover agents that provide a specific capability. Filter by trust score, latency, and success rate.

Path Parameters

Parameter	Type	Required	Description
capability_id	string	required	Capability to search for

Query Parameters

Parameter	Type	Required	Description
min_trust	number	optional	Minimum trust score (0-100)
max_latency	number	optional	Maximum avg latency in ms

Example Request

curl "https://cap402.com/a2a/discover/cap.price.lookup.v1?min_trust=50"

Response

{ "agents": [ { "agent_id": "price-oracle", "trust_score": 87, "avg_latency_ms": 45, "success_rate": 0.99, "total_invocations": 12450 } ], "total": 3 }

POST /a2a/auction Agents compete to fulfill request

Description

Create an auction where multiple agents bid to fulfill a capability request. Winner selected by price, trust, and latency.

Request Body

Parameter	Type	Required	Description
requester_agent	string	required	Agent requesting the auction
capability_id	string	required	Capability to auction
max_price	number	optional	Maximum acceptable bid
inputs	object	optional	Capability inputs

Example Request

curl -X POST https://cap402.com/a2a/auction \
  -H "Content-Type: application/json" \
  -d '{
    "requester_agent": "my-trading-bot",
    "capability_id": "cap.price.lookup.v1",
    "max_price": 10
  }'

Response

{ "auction_id": "auc_xyz789", "winner": { "agent_id": "price-oracle", "bid": 5, "trust_score": 87 }, "total_bids": 4, "outputs": { "price": 185.42 } }

POST /a2a/swarm Coordinate multiple agents

Description

Execute a task across multiple agents. Supports parallel (all at once) or sequential (one after another) strategies.

Request Body

Parameter	Type	Required	Description
coordinator_agent	string	required	Agent coordinating the swarm
task	object	required	Task with `capability_id` and `inputs`
agents	string[]	required	Array of agent IDs to include
strategy	string	optional	`parallel` or `sequential` (default)

Example Request

curl -X POST https://cap402.com/a2a/swarm \
  -H "Content-Type: application/json" \
  -d '{
    "coordinator_agent": "orchestrator",
    "task": { "capability_id": "cap.price.lookup.v1" },
    "agents": ["bot-1", "bot-2", "bot-3"],
    "strategy": "parallel"
  }'

Response

{ "swarm_id": "swm_abc123", "strategy": "parallel", "results": [ { "agent": "bot-1", "success": true, "latency_ms": 45 }, { "agent": "bot-2", "success": true, "latency_ms": 52 }, { "agent": "bot-3", "success": true, "latency_ms": 38 } ], "total_time_ms": 52 }

GET /a2a/leaderboard Agent reputation rankings

Description

Get ranked list of agents by composite reputation score. Score is calculated from trust, success rate, latency, and capabilities count.

Query Parameters

Parameter	Type	Required	Description
limit	number	optional	Max results (default: 10, max: 100)
sort_by	string	optional	`composite_score`, `trust_score`, `total_invocations`

Example Request

curl "https://cap402.com/a2a/leaderboard?limit=5"

Response

{ "leaderboard": [ { "rank": 1, "agent_id": "price-oracle", "composite_score": 94.5, "trust_score": 87, "success_rate": 0.99, "total_invocations": 12450 } ], "total_agents": 47 }

MEV Protection

POST /mev/analyze Analyze sandwich attack risk

Description

Analyze a potential trade for MEV risk. Returns sandwich attack probability, potential loss estimate, and protection recommendations.

Request Body

Parameter	Type	Required	Description
token_in	string	required	Input token symbol or mint address
token_out	string	required	Output token symbol or mint address
amount	number	required	Amount in token_in units
slippage	number	optional	Slippage tolerance % (default: 0.5)

Example Request

curl -X POST https://cap402.com/mev/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "token_in": "SOL",
    "token_out": "USDC",
    "amount": 10000,
    "slippage": 0.5
  }'

Response

{ "risk_level": "high", "sandwich_probability": 0.73, "estimated_loss_usd": 542.50, "recommendation": "Use protected swap", "analysis": { "pool_liquidity": 2450000, "trade_impact_bps": 41, "recent_mev_activity": true } }

POST /mev/protected-swap Execute with MEV protection

Description

Execute a swap via private mempool (Arcium MPC) for MEV protection. Trade details are hidden from public mempool.

Request Body

Parameter	Type	Required	Description
token_in	string	required	Input token
token_out	string	required	Output token
amount	number	required	Amount to swap
wallet_address	string	required	Destination wallet
protection_level	string	optional	`standard`, `enhanced`, `maximum`

Example Request

curl -X POST https://cap402.com/mev/protected-swap \
  -H "Content-Type: application/json" \
  -d '{
    "token_in": "SOL",
    "token_out": "USDC",
    "amount": 100,
    "wallet_address": "ABC123...",
    "protection_level": "maximum"
  }'

Response

{ "success": true, "tx_signature": "5xYz...", "amount_received": 18542.50, "mev_saved_usd": 127.30, "protection": { "level": "maximum", "method": "arcium_mpc" } }

Trading Alpha

GET /alpha/arbitrage Cross-DEX arbitrage opportunities

Description

Find real-time arbitrage opportunities across DEXs. Returns profitable routes with estimated profit after gas.

Query Parameters

Parameter	Type	Required	Description
min_profit_bps	number	optional	Minimum profit in basis points (default: 5)
max_results	number	optional	Max opportunities to return (default: 10)

Example Request

curl "https://cap402.com/alpha/arbitrage?min_profit_bps=10"

Response

{ "opportunities": [ { "pair": "SOL/USDC", "buy_dex": "raydium", "sell_dex": "orca", "profit_bps": 23, "profit_usd": 42.50, "expires_in_ms": 1500 } ], "scanned_pairs": 847 }

GET /alpha/whale-tracker Monitor large wallet movements (Live Helius Data)

Description

Track real whale movements using Helius Enhanced Transactions API. Monitors known whale wallets (Jump Trading, large SOL holders, protocol treasuries) for swaps and transfers. Returns market sentiment derived from buy/sell volume analysis.

Data Sources

• Helius - Real-time transaction data with 3 API keys for high availability
• Nansen - Smart money labels and wallet categorization (when credits available)
• Jupiter - Current token prices for USD valuations

Query Parameters

Parameter	Type	Required	Description
token	string	optional	Filter by token symbol (SOL, USDC, JUP, BONK)
min_value	number	optional	Minimum USD value (default: 100000)

Example Request

curl "https://cap402.com/alpha/whale-tracker?token=SOL&min_value=500000"

Response

{ "whale_tracker": { "movements": [ { "wallet": "FWzn...ouN5", "wallet_label": "Jump Trading (smart_money)", "action": "buy", "token": "SOL", "amount": 50000, "value_usd": 7250000, "signature": "h8ui...fLiP", "significance": "BULLISH - Large accumulation" } ], "summary": { "total_movements": 5, "buy_volume_usd": 45000000, "sell_volume_usd": 12000000, "net_flow_usd": 33000000, "market_sentiment": "BULLISH" }, "data_source": "helius_enhanced_transactions + nansen_labels" } }

GET /alpha/smart-money Smart Money Activity (Live Nansen Data)

Description

Track what smart money wallets are buying and selling using Nansen TGM API. Returns labeled traders (funds, whales, smart traders) with their 24h buy/sell volumes and net flow.

Data Source

• Nansen - Token God Mode who-bought-sold endpoint (1 credit per call)

Query Parameters

Parameter	Type	Required	Description
token	string	optional	Token symbol: SOL, JUP, BONK, WIF, PYTH (default: SOL)

Example Request

curl "https://cap402.com/alpha/smart-money?token=SOL"

Response

{ "smart_money": { "token": "SOL", "traders": [ { "address": "8aHV...3MXx", "label": "Active SOL Millionaire", "bought_volume_usd": 1578603615, "sold_volume_usd": 38696321, "net_volume_usd": 1539907293, "action": "accumulating" } ], "summary": { "accumulators": 14, "distributors": 3, "net_flow_usd": 24500000, "sentiment": "BULLISH" }, "data_source": "nansen_tgm_who_bought_sold" } }

GET /alpha/liquidations DeFi liquidation opportunities

Description

Monitor at-risk DeFi positions approaching liquidation thresholds. Returns positions sorted by proximity to liquidation.

Query Parameters

Parameter	Type	Required	Description
protocol	string	optional	Filter by protocol: `solend`, `mango`, `marginfi`
min_value	number	optional	Minimum position value USD

Example Request

curl "https://cap402.com/alpha/liquidations?min_value=10000"

Response

{ "at_risk_positions": [ { "protocol": "solend", "wallet": "DEF...789", "collateral_usd": 125000, "debt_usd": 98000, "health_factor": 1.05, "liquidation_price": 172.50, "current_price": 185.42 } ], "total_at_risk_usd": 4250000 }

Agents

POST /agents/register Register a new agent

Description

Request Body

Parameter	Type	Required	Description
agent_id	string	required	Unique agent identifier (alphanumeric, hyphens)
name	string	required	Human-readable agent name
capabilities_provided	string[]	optional	Capabilities this agent can fulfill
webhook_url	string	optional	URL for receiving invocation requests

Example Request

curl -X POST https://cap402.com/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-trading-bot",
    "name": "My Trading Bot",
    "capabilities_provided": ["cap.price.lookup.v1"],
    "webhook_url": "https://mybot.com/webhook"
  }'

Response

{ "success": true, "agent": { "agent_id": "my-trading-bot", "api_key": "cap_sk_...", "trust_score": 50, "created_at": 1705347600000 } }

Errors

400Invalid agent_id format
409Agent ID already exists

System

GET /sponsors/health Sponsor integration health

Description

Check connectivity and status of all sponsor integrations (Arcium, Noir, Helius, Inco).

Example Request

curl https://cap402.com/sponsors/health

Response

{ "overall_status": "healthy", "sponsors": { "arcium": { "status": "connected", "latency_ms": 45 }, "noir": { "status": "connected", "latency_ms": 12 }, "helius": { "status": "connected", "latency_ms": 28 }, "inco": { "status": "connected", "latency_ms": 67 } }, "last_check": 1705347600000 }

GET /system/dashboard Real-time system overview

Description

Get comprehensive system status including capabilities, agents, invocations, and performance metrics.

Example Request

curl https://cap402.com/system/dashboard

Response

{ "capabilities": { "total": 13, "active": 13 }, "agents": { "registered": 47, "active_24h": 23 }, "invocations": { "total_24h": 145230, "success_rate": 0.987, "avg_latency_ms": 89 }, "privacy": { "confidential_ratio": 0.77, "zk_proofs_generated": 12450 }, "sponsors": { "all_healthy": true }, "uptime_percent": 99.97 }

Confidential Execution Pipeline

POST /execute/confidential Full confidential pipeline (Noir→Inco→Arcium→Noir)

Description

Execute with full confidential pipeline. Chains ZK eligibility proof → FHE encryption → MPC execution → execution proof. Mandatory for trades >$100K.

Request Body

Parameter	Type	Required	Description
agent_id	string	required	Agent identifier
operation	string	required	swap \| transfer \| bid \| vote \| delegate \| prove
amount_usd	number	required	Trade size in USD
inputs	object	optional	Operation-specific inputs
required_proofs	string[]	optional	ZK proofs to generate (e.g., balance_threshold)
privacy_level	string	optional	public \| protected \| confidential \| maximum

Example Request

curl -X POST https://cap402.com/execute/confidential \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "operation": "swap",
    "amount_usd": 150000,
    "inputs": { "token_in": "SOL", "token_out": "USDC" },
    "required_proofs": ["balance_threshold"]
  }'

Response

{ "success": true, "execution_id": "exec_1705347600_a1b2c3d4", "tier": "confidential", "stages_completed": ["noir_eligibility", "inco_encrypt", "arcium_mpc", "noir_execution_proof"], "fee_usd": 150, "slippage_saved_bps": 145, "total_time_ms": 3847 }

POST /execute/tier Determine required execution tier

Description

Check what execution tier is required/recommended for a given trade size.

Request Body

Parameter	Type	Required	Description
amount_usd	number	required	Trade size in USD

Response

{ "success": true, "amount_usd": 150000, "tier": "confidential", "thresholds": { "ARCIUM_MANDATORY": 100000, "INCO_RECOMMENDED": 50000 }, "recommendation": "MANDATORY: Use /execute/confidential for MEV protection" }

POST /execute/threshold-sign Multi-party threshold signature

Description

Generate a threshold signature where multiple parties sign without revealing individual keys.

Request Body

Parameter	Type	Required	Description
signers	string[]	required	Array of signer identifiers
threshold	number	required	Minimum signers required (e.g., 2 of 3)
message_hash	string	required	Hash of message to sign

POST /execute/multi-swap Atomic multi-party swap

Description

Execute atomic swaps between multiple parties simultaneously without revealing individual amounts.

POST /execute/orderbook Create encrypted orderbook

Description

Create a dark pool orderbook where prices and sizes are encrypted with FHE.

Request Body

Parameter	Type	Required	Description
asset_pair	string	required	Trading pair (e.g., "SOL/USDC")

POST /execute/orderbook/:id/order Submit encrypted order

POST /execute/orderbook/:id/match Match orders via FHE comparison

POST /execute/auction Create private auction

Description

Create a sealed-bid auction where bids are encrypted. Winner determined without revealing losing bids.

Request Body

Parameter	Type	Required	Description
auctioneer	string	required	Auctioneer agent ID
asset	string	required	Asset being auctioned
reserve_price	number	optional	Encrypted reserve price

POST /execute/auction/:id/bid Submit encrypted bid

POST /execute/auction/:id/settle Settle auction

POST /execute/prove-performance Generate performance proof

Description

Prove agent performance metrics (win rate, volume, profitability) without revealing strategy details.

Request Body

Parameter	Type	Required	Description
agent_id	string	required	Agent identifier
metrics	object	required	{ total_trades, profitable_trades, total_volume_usd, total_pnl_usd }
claim_type	string	required	win_rate \| volume \| profitability

GET /execute/stats Pipeline statistics

Response

{ "success": true, "execution_count": 1234, "total_volume_usd": 45000000, "total_fees_usd": 45000, "active_orderbooks": 12, "active_auctions": 5, "avg_fee_rate_bps": 10 }

🥷 Pump.fun Privacy — Privacy-First Token Launches

POST /unified/launch Execute unified privacy-first token launch

Description

Launch a token on pump.fun via pumpfun.fun with privacy features: hidden creator wallet, MEV protection, timing obfuscation. Creator revealed only on graduation (85 SOL).

Request Body

Parameter	Type	Required	Description
token	object	required	{ name, symbol, description, image?, twitter?, telegram?, website? }
initial_buy_sol	number	required	Initial buy amount in SOL
privacy_level	string	optional	basic \| enhanced \| maximum (default: enhanced)
slippage_bps	number	optional	Slippage tolerance in basis points (default: 500)

Example Request

curl -X POST https://cap402.com/unified/launch \
  -H "Content-Type: application/json" \
  -d '{
    "token": {"name": "StealthCoin", "symbol": "STEALTH", "description": "Privacy-first launch"},
    "initial_buy_sol": 1.5,
    "privacy_level": "enhanced"
  }'

Response

{ "success": true, "mint_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", "pump_fun_url": "https://pump.fun/7xKXtg...", "privacy_level": "enhanced", "privacy_score": 85, "privacy_grade": "A", "creator_hidden": true, "mev_protected": true }

GET /unified/dashboard/:mint_address Aggregated dashboard data from all systems

Description

Get unified dashboard data combining CAP-402 privacy metrics, Pump.fun Privacy registry, and pump.fun market data.

Response

{ "token": { "mint": "...", "name": "StealthCoin", "symbol": "STEALTH" }, "market": { "bonding_curve_progress": 45.2, "sol_raised": 38.4, "graduated": false }, "privacy": { "score": 85, "grade": "A", "creator_revealed": false }, "anonymity": { "score": 72, "total_holders": 156, "anonymous_holders": 112 } }

GET /unified/privacy-presets Get privacy configuration presets

Description

Returns available privacy presets: basic (hidden creator), enhanced (+ MEV protection, timing obfuscation), maximum (+ no auto-reveal, Noir ZK proofs).

GET /unified/status System integration status

Description

Check status of CAP-402, Pump.fun Privacy, and pump.fun integration. Returns operational status, active launches, and integration health.

GET /pumpfun/privacy-score/:mint_address Get privacy score for a token

Description

Calculate comprehensive privacy score (0-100) with grade (A-F) based on: creator visibility, holder anonymity, funding obfuscation, MEV protection, timing patterns.

Response

{ "success": true, "privacy_score": 85, "grade": "A", "factors": { "creator_hidden": true, "holder_anonymity": 72, "funding_obfuscated": true, "mev_protected": true, "timing_obfuscated": true } }

GET /pumpfun/stealth/view/:mint_address Privacy-preserving token view

Description

View token data with creator hidden until graduation. Shows bonding curve progress, market cap, but masks creator wallet.

GET /pumpfun/monitor/:mint_address Start graduation monitoring

Description

Monitor a token for graduation (85 SOL threshold). Returns current progress and emits events on graduation.

GET /pumpfun/anonymity/:mint_address Holder anonymity analysis

Description

Analyze holder distribution for anonymity. Tracks anonymous vs revealed holders, concentration metrics, and deanonymization risks.

GET /pumpfun/pumpfun-data/:mint_address Pump.fun compatible data format

Description

Returns token data in pump.fun's exact format for frontend compatibility. Includes bonding curve progress, market cap, and display formatting.