Agent API · v1

Hire a growth coach from your agent

Gardenpatch coaches are callable over HTTP and priced per call. Your agent pays with x402 — no signup, no API key, no human with a credit card. Send a request, get a 402 with the price, pay, retry. That's the whole integration.

Every call returns the same envelope: a diagnosis, the arithmetic behind it, concrete actions, and a typed deliverable that depends on the mode you asked for.

Quickstart

Call it unpaid first. You'll get 402 with machine-readable payment requirements and the full catalog — that response is designed to be enough for an agent to figure out the rest on its own.

curl -sS -X POST https://gardenpatch.xyz/api/v1/agents/mary/call \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "diagnose_growth",
    "messages": [
      { "role": "user", "content": "Revenue has been flat at $40k/mo for two quarters. Where are we stuck?" }
    ],
    "context": {
      "company": { "what_they_sell": "HVAC maintenance plans", "stage": "scaling" },
      "metrics": { "monthly_revenue_usd": 40000, "leads_per_month": 120, "close_rate_pct": 18 }
    }
  }'

Agents

One URL shape: POST /api/v1/agents/{agent_id}/call

Modes & pricing

The mode you pass decides the price and the shape of deliverable. You only pay for successful calls — a 4xx or 5xx settles nothing.

Response

{
  "agent": "mary",
  "mode": "diagnose_growth",
  "reply": "Your problem isn't lead volume — it's that 18% close rate...",
  "thinking": {
    "diagnosis": "Conversion, not demand",
    "lever": "Rebuild the offer around a guaranteed outcome",
    "confidence": "high"
  },
  "numbers": [
    { "label": "Revenue per lead", "value": "$333", "basis": "$40,000 / 120 leads" }
  ],
  "actions": [
    {
      "title": "Rewrite the maintenance plan offer",
      "steps": ["Name the outcome and time frame", "Add a specific guarantee"],
      "effort": "days",
      "metric": "Close rate — target 18% to 25% within 60 days"
    }
  ],
  "caveats": ["Stated AOV and monthly revenue imply different close rates; used the stated AOV."],
  "deliverable": { "...": "mode-specific, see the schema for this mode" },
  "context_gaps": [],
  "usage": { "input_tokens": 1204, "output_tokens": 861 }
}

caveats is the only field that carries uncertainty — if your inputs contradict each other, the coach picks a reading, uses it consistently, and tells you here. Every other field is a settled conclusion you can parse without stripping hedges out of it.

context_gaps lists the recommended context fields you left out. Fill them in and the next call gets materially sharper — that field exists so an agent can self-correct without reading these docs.

Sending context

Everything in context is optional, but the coaches are numerate — give them numbers and you get arithmetic instead of adjectives. Each mode names what it wants:

Typed schemas

Every mode publishes JSON Schema for both sides of the call, generated from the same definitions the API validates against. Import them and each mode becomes a distinct strongly-typed tool in your framework.

GET /api/v1/schemas/{mode}/request.json
GET /api/v1/schemas/{mode}/response.json
GET /api/v1/openapi.json      # full OpenAPI 3.1 document
GET /api/v1/agents            # live catalog — free, no payment

Registering a mode as a tool (Claude / OpenAI tool-calling shape):

{
  "name": "gardenpatch_diagnose_growth",
  "description": "Find the one binding growth constraint for a business and rank the levers against it. Returns a diagnosis, supporting arithmetic, and concrete actions.",
  "input_schema": { "$ref": "https://gardenpatch.xyz/api/v1/schemas/diagnose_growth/request.json" }
}

Paying

Use any x402 client. The wrapper handles the 402 → pay → retry handshake, so your code looks like a normal fetch:

import { wrapFetchWithPayment } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });

// Handles the 402 → pay → retry handshake for you.
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

const res = await fetchWithPay("https://gardenpatch.xyz/api/v1/agents/mary/call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    mode: "diagnose_growth",
    messages: [{ role: "user", content: "Where is our growth stuck?" }],
    context: { metrics: { monthly_revenue_usd: 40000, leads_per_month: 120 } },
  }),
});

const { reply, thinking, actions } = await res.json();

Errors & what you're charged for

Settlement happens only after a successful response. You are never charged for a malformed request, a rate limit, a capacity refusal, or a model failure on our side.

What we do with what you send

The messages and context you send are forwarded to Anthropic to generate the response, and we log token counts for billing and capacity. Send business context, not personal data about your customers — this endpoint is built for company metrics, offers, and positioning, and nothing in the schema asks for anything else.

Contract stability

This is a versioned interface under /v1. We may add optional fields. We will not rename a field, make an optional field required, or narrow an enum without shipping /v2 alongside it.

Building something with this? Tell us what you need — we'll prioritise modes that people are actually calling.