graded-x402

Search the graded catalog of x402 services (ours + the Bazaar), ranked by real 30-day demand and agent-usability grade (A-F). Free.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "substring match on name/description"
    },
    "grade": {
      "type": "string",
      "description": "comma list of grades, e.g. \"A,B\""
    },
    "callable": {
      "type": "boolean",
      "description": "only services callable through the gateway"
    },
    "offset": {
      "type": "number",
      "description": "pagination offset"
    },
    "limit": {
      "type": "number",
      "description": "max 100 per page"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full detail for one catalog service: grade breakdown, live price, our price (incl. markup), input schema, output example. Free.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Call a catalog service through the gateway. The gateway pays the upstream x402 USDC price from its own wallet and deducts your prepaid credits (upstream price + 25% markup, min $0.005). Requires an account key with credits.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "query": {
      "type": "object",
      "additionalProperties": {},
      "description": "URL query params"
    },
    "body": {
      "description": "JSON body for POST services"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a gateway account. Returns your secret key (gwk_…) - store it; it is shown only once. New accounts start at 0 credits.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Your balance, totals, limits, and recent calls. Requires Authorization: Bearer <gwk_ key>.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Configure YOUR account's spending guardrails, enforced on every call_service: max_call_usd (refuse any call charging more), daily_usd (rolling-24h charge budget), min_grade (refuse services graded below it), allow (exact service-id allowlist). Send only fields to change; null clears a field. Requires Authorization: Bearer <gwk_ key>.

{
  "type": "object",
  "properties": {
    "max_call_usd": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 100
        },
        {
          "type": "null"
        }
      ],
      "description": "max USD charged per call"
    },
    "daily_usd": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000
        },
        {
          "type": "null"
        }
      ],
      "description": "max USD charged per rolling 24h"
    },
    "min_grade": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "A",
            "B",
            "C",
            "D"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "refuse services graded below this"
    },
    "allow": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "service-id allowlist; only these are callable"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One-time: mint a separate OWNER key (gwo_…) for the human supervisor. After this, the gwk_ agent key can spend and TIGHTEN limits but never loosen or clear them; only the owner key can. Shown once - the human should store it where the agent can't read it. Requires Authorization: Bearer <gwk_ key>.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

How to add credits (x402 USDC, or a card checkout link via create_topup_link).

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a hosted card-payment link (Stripe Checkout) that adds $5, $10 or $20 of credits to YOUR account. Give the returned url to your human to open and pay - no crypto wallet needed; credits land 1:1 within seconds of payment. Requires Authorization: Bearer <gwk_ key>.

{
  "type": "object",
  "properties": {
    "pack": {
      "type": "number",
      "description": "USD amount: 5, 10 or 20"
    }
  },
  "required": [
    "pack"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}