Discovery Protocol

JarvisClaw exposes a standard x402 discovery endpoint that any agent can query to learn about available services and payment methods.

Discovery Endpoint

bash

curl https://api.jarvisclaw.ai/.well-known/x402

/.well-known/x402 is the canonical path — it is what x402scan and other agent tooling probe. /.well-known/x402/discovery is retained as a legacy alias.

No authentication required. Returns:

json

{
  "x402Version": 2,
  "provider": {
    "name": "JarvisClaw",
    "description": "AI API routing platform with smart routing, pay per call via x402",
    "url": "https://api.jarvisclaw.ai",
    "docs": "https://docs.jarvisclaw.ai"
  },
  "paymentInfo": {
    "protocol": "x402",
    "version": "2",
    "networks": ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
    "assets": {
      "eip155:8453": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "solana:...": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    },
    "payTo": { "eip155:8453": "0x...", "solana:...": "..." },
    "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402"
  },
  "resources": [...],
  "capabilities": {
    "streaming": true,
    "multimodal": true,
    "functionCalling": true,
    "vision": true,
    "codeExecution": true,
    "webSearch": true,
    "openaiCompatible": true,
    "claudeCompatible": true,
    "geminiCompatible": true
  },
  "authentication": {
    "x402": { "header": "PAYMENT-SIGNATURE", "headerAliases": ["X-PAYMENT"] },
    "apiKey": { "header": "Authorization", "format": "Bearer sk-..." }
  },
  "discovery": {
    "llmsTxt": "/llms.txt",
    "agentManifest": "/agent-manifest.json",
    "openapi": "/openapi.json",
    "a2aCard": "/.well-known/agent.json",
    "aip": "/.well-known/agent-intent-protocol.json",
    "mcp": "/mcp",
    "models": "/v1/models",
    "health": "/api/discovery/health"
  }
}

The discovery block cross-links every other machine-readable surface, so an agent that finds any one of them can reach the rest.

Resources

Each entry in resources carries a type, endpoint, methods, description, pricing, and a concrete price where one is known — so an agent can compare providers without probing every endpoint for a 402. Representative entries:

Type	Endpoint	Description
`ai-model`	`/v1/chat/completions`	Chat completions (per-token)
`ai-model`	`/v1/messages`	Anthropic-native Messages API
`ai-model`	`/v1/responses`, `/v1/responses/compact`	Responses API (stateful agent runs)
`ai-model`	`/v1/images/generations`, `/v1/images/edits`	Image generation and editing
`ai-model`	`/v1/videos/generations`	Video generation
`ai-model`	`/v1/audio/speech`, `/audio/transcriptions`, `/audio/translations`, `/audio/generations`	Speech, transcription, translation, music
`ai-model`	`/v1/embeddings`, `/v1/rerank`	Embeddings and reranking
`ai-model`	`/v1/realtime`	WebSocket realtime (voice-to-voice, low-latency text)
`ai-model`	`/v1/moderations`	Content safety classification
`ai-tool`	`/v1/search`	Web/knowledge search
`ai-tool`	`/v1/prompt-coach/optimize`	Prompt optimization
`agent-protocol`	`/v1/intent/*`	AIP — resolve, execute, execute-budget, subscribe, discover
`agent-protocol`	`/a2a`	A2A JSON-RPC entry point
`agent-protocol`	`/mcp`	MCP server (Streamable HTTP)
`marketplace`	`/v1/marketplace/<service>/...`	One entry per marketplace service, individually priced
`user-api`	`/v1/uapi/{slug}/{path}`	User-published APIs (per-call billing)
`agent-registry`	`/api/agents`	Discover other agents

Marketplace services are enumerated individually

Each marketplace service appears as its own resource with a real callable path and price. There is no single /v1/marketplace/{service}/{path} placeholder entry to parse.

Get Model List

The discovery endpoint doesn't include the full model list (to avoid stale data). Query models directly:

bash

curl https://api.jarvisclaw.ai/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

AIP Discovery (Agent Intent Protocol)

In addition to x402 discovery, JarvisClaw exposes a standard AIP endpoint for agent-to-agent discovery:

bash

curl https://api.jarvisclaw.ai/.well-known/agent-intent-protocol.json

Response:

json

{
  "aip_version": "1.0",
  "name": "JarvisClaw AI Gateway",
  "description": "Unified AI service gateway with x402 on-chain micropayment. Agents discover, resolve, and execute AI capabilities across a decentralized network of providers.",
  "endpoints": {
    "discover":       { "method": "GET",  "url": "https://api.jarvisclaw.ai/v1/intent/discover", "auth": "none" },
    "resolve":        { "method": "GET",  "url": "https://api.jarvisclaw.ai/v1/intent/resolve",  "auth": "none" },
    "types":          { "method": "GET",  "url": "https://api.jarvisclaw.ai/v1/intent/types",    "auth": "none" },
    "execute":        { "method": "POST", "url": "https://api.jarvisclaw.ai/v1/intent/execute",  "auth": "x402_payment" },
    "execute_budget": { "method": "POST", "url": "https://api.jarvisclaw.ai/v1/intent/execute-budget", "auth": "x402_payment" },
    "subscribe":      { "method": "POST", "url": "https://api.jarvisclaw.ai/v1/intent/subscribe", "auth": "x402_payment" }
  },
  "network": {
    "description": "Public catalogue of third-party API servers.",
    "endpoints": {
      "search":    { "method": "GET",  "url": ".../v1/network/search",    "auth": "none" },
      "servers":   { "method": "GET",  "url": ".../v1/network/servers",   "auth": "none" },
      "apis":      { "method": "GET",  "url": ".../v1/network/apis",      "auth": "none" },
      "health":    { "method": "GET",  "url": ".../v1/network/health",    "auth": "none" },
      "recommend": { "method": "POST", "url": ".../v1/network/recommend", "auth": "none" },
      "execute":   { "method": "POST", "url": ".../v1/network/execute",   "auth": "x402_payment" }
    }
  },
  "federation": { "...": "deprecated alias, identical payload to \"network\"" },
  "wallet": {
    "base_url": "https://api.jarvisclaw.ai/v1/wallet",
    "endpoints": ["/balance", "/history", "/limits", "/pools"],
    "auth": "x402_payment"
  },
  "supported_intents": ["chat_completion", "image_generation", "..."],
  "protocols": ["aip/1.0", "a2a/1.0", "mcp/1.0"],
  "payment": {
    "method": "x402",
    "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402",
    "networks": [
      { "name": "base", "chain_id": 8453, "token": "USDC" },
      { "name": "base-sepolia", "chain_id": 84532, "token": "USDC", "testnet": true },
      { "name": "solana", "cluster": "mainnet-beta", "token": "USDC" }
    ],
    "flow": [
      "1. Agent calls endpoint → receives 402 with payment requirements",
      "2. Agent signs x402 payment header with USDC",
      "3. Agent retries request with PAYMENT-SIGNATURE header (X-PAYMENT is also accepted)",
      "4. Gateway verifies payment on-chain and fulfills request"
    ]
  },
  "attestation": {
    "description": "Paid responses include a signed 'settlement' receipt, verifiable offline.",
    "enabled": true,
    "signer": "0x...",
    "scheme": "eip712",
    "domain": { "name": "JarvisClaw-AIP", "version": "1", "chainId": 8453 }
  },
  "authentication": {
    "primary": "x402_payment",
    "methods": [
      { "type": "x402_payment", "header": "PAYMENT-SIGNATURE", "headerAliases": ["X-PAYMENT"] },
      { "type": "bearer_token", "description": "Session token from web login" }
    ]
  },
  "docs": "https://docs.jarvisclaw.ai",
  "contact": "https://t.me/JarvisClawai"
}

supported_intents is generated from the live provider registry, so it grows as network peers join. Each endpoint entry carries its own auth field — read that rather than assuming.

This is how other agents and platforms automatically discover your services. Any platform that crawls /.well-known/agent-intent-protocol.json can find and integrate with JarvisClaw.

Verifying settlement receipts

The attestation block advertises the EIP-712 signer for settlement receipts. Paid responses carry a settlement.attestation object you can verify offline — recompute the intent and result hashes, recover the signer, and compare it to attestation.signer here. See AIP → Settlement.

A2A Discovery (Agent-to-Agent)

JarvisClaw also serves a Google A2A Agent Card, so A2A-aware clients can discover it and delegate tasks over JSON-RPC.

bash

# Spec path (registered with IANA, required by the A2A spec)
curl https://api.jarvisclaw.ai/.well-known/agent-card.json

# Pre-1.0 alias, retained for older clients
curl https://api.jarvisclaw.ai/.well-known/agent.json

Both paths serve the same card and need no authentication. The card advertises skills covering chat, image, video, speech, search, and embeddings, each with example prompts.

Calling A2A

bash

curl -X POST https://api.jarvisclaw.ai/a2a \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Summarize the latest AI agent research"}]
      }
    }
  }'

JSON-RPC methods:

Method	Legacy 0.x alias	Description
`SendMessage`	`tasks/send`	Submit a task
`GetTask`	`tasks/get`	Poll task state
`CancelTask`	`tasks/cancel`	Cancel a task

A2A 1.0 renamed these; the 0.x names are still accepted. POST /a2a uses the same auth as everything else — an API key, or an x402 payment signature for wallet-paying agents. Fetching the card is free; task execution is billed.

Network

When the network is enabled, your platform also discovers and aggregates services from other AIP-compatible platforms. Network results are merged into /v1/intent/discover responses automatically.

See AIP → Network for peer management, the recommend tiers, and how to join the network as a peer.

Alternative Probe Paths

Agents commonly try these paths:

Path	Behaviour
`/.well-known/x402`	Canonical x402 discovery
`/.well-known/x402/discovery`	Legacy alias, same payload
`/.well-known/agent-intent-protocol.json`	Canonical AIP discovery
`/.well-known/agent-card.json`	Canonical A2A card
`/.well-known/agent.json`	Legacy A2A alias
`/x402/discovery`	301 → `/.well-known/x402`
`/discovery/resources`	301 → `/.well-known/x402`

Public Discovery API

Free, unauthenticated JSON for tooling that wants a lighter payload than full discovery:

bash

curl https://api.jarvisclaw.ai/api/discovery/models       # model list
curl https://api.jarvisclaw.ai/api/discovery/free-models  # free models only
curl https://api.jarvisclaw.ai/api/discovery/health       # platform health
curl https://api.jarvisclaw.ai/v1/network/stats           # AIP network size (counts only)

Plain-text and manifest surfaces for crawlers and agent tooling:

bash

curl https://api.jarvisclaw.ai/llms.txt
curl https://api.jarvisclaw.ai/agent-manifest.json

OpenAPI Spec

For x402scan and automated tooling:

bash

curl https://api.jarvisclaw.ai/openapi.json

Returns OpenAPI 3.1 spec with x-payment-info on each paid endpoint.

Discovery Protocol ​

Discovery Endpoint ​

Resources ​

Get Model List ​

AIP Discovery (Agent Intent Protocol) ​

Verifying settlement receipts ​

A2A Discovery (Agent-to-Agent) ​

Calling A2A ​

Network ​

Alternative Probe Paths ​

Public Discovery API ​

OpenAPI Spec ​

Discovery Protocol

Discovery Endpoint

Resources

Get Model List

AIP Discovery (Agent Intent Protocol)

Verifying settlement receipts

A2A Discovery (Agent-to-Agent)

Calling A2A

Network

Alternative Probe Paths

Public Discovery API

OpenAPI Spec