Agent Economy (AIP)

The Agent Intent Protocol lets autonomous agents discover optimal AI providers, manage budgets, and pay only for what they use — all through a single API.

How It Works

Agent declares intent → AIP finds best provider → Agent calls model → Treasury tracks spending

1. Intent Resolution (free) — declare what you need, get ranked providers
2. Execute — call the recommended model with your API key or x402 payment
3. Wallet Management — check balance, set limits, track spending pools

Quick Start

Find the Best Model

curl

curl -X POST https://api.jarvisclaw.ai/v1/intent/resolve \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "chat_completion",
    "constraints": { "max_price_usd": 0.01 },
    "preferences": { "optimize_for": "cost" }
  }'

Python

from jarvisclaw import Agent

agent = Agent(api_key="sk-YOUR-KEY")

# One line: find best model + call it
result = agent.ask("Explain quantum computing", budget=0.01, optimize="cost")
print(result)

Go

import jc "github.com/api-jarvisclaw/go-sdk/v2"

c, _ := jc.NewClient(jc.WithAPIKey("sk-YOUR-KEY"))
text, _ := c.Ask(ctx, "Explain quantum computing",
    jc.AskOptions{Budget: 0.01, Optimize: "cost"})
fmt.Println(text)

Response

{
  "matches": [
    {
      "provider_id": "deepseek-chat",
      "score": 0.95,
      "estimated_price_usd": 0.0003,
      "endpoint": "/v1/chat/completions",
      "model": "deepseek-chat",
      "reason": "lowest cost: $0.000300/req"
    }
  ],
  "intent_type": "chat_completion",
  "total_available": 45
}

Use the Recommended Model

curl https://api.jarvisclaw.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "Hello!"}]}'

Intent Types

Intent	Description	Example Models
chat_completion	Text generation / chat	GPT-5.x, Claude 4.x, DeepSeek, Gemini 3.x
image_generation	Image creation	GPT-Image, Nano Banana, CogView, Grok Imagine
video_generation	Video synthesis	Sora 2, Seedance 2.0
text_to_speech	TTS audio	ElevenLabs
web_search	Web browsing	Surf (83 endpoints)
knowledge_search	Semantic search	Exa

Thirteen intent types are defined locally and network peers add more. See AIP → Supported Intent Types, or query GET /v1/intent/types for the live list.

Optimization Strategies

Strategy	Behavior
cost	Cheapest model that meets constraints (default)
quality	Highest quality score (benchmark-based)
latency	Fastest response time (P95 measured)
budget	Weights payment overhead heavily — for tight per-call budgets

Constraints

{
  "constraints": {
    "max_price_usd": 0.01,
    "max_latency_ms": 3000,
    "features": ["function_calling", "vision", "streaming"]
  }
}

Authentication

Discovery is free and unauthenticated — GET /v1/intent/types, GET /v1/providers and GET /v1/network/stats need no credentials.

Ranked resolution and every execute path do require auth: they consume embedding and upstream resources. Three methods are supported:

Method	Header	Use Case
API Key	Authorization: Bearer sk-xxx	SDK users, developers
x402 Payment	PAYMENT-SIGNATURE: <signed> (or X-PAYMENT)	Autonomous agents (zero registration)
Session Cookie	(automatic)	Dashboard users

POST /v1/intent/resolve is authenticated

The GET form of that path returns usage documentation and is free. The POST form performs the actual ranking and requires a credential.

API Endpoints

Method	Path	Auth	Description
POST	/v1/intent/resolve	Required	Resolve intent to ranked providers
POST	/v1/intent/resolve/natural	Required	Natural-language resolution
POST	/v1/intent/execute	Required	Resolve + execute in one call
POST	/v1/intent/execute-budget	Required	Execute under a hard budget cap
GET	/v1/intent/types	None	List supported intent types
GET	/v1/providers	None	List all registered providers
GET	/v1/network/stats	None	Aggregate network size

Full reference: Agent Intent Protocol.