{ "openapi": "3.1.0", "info": { "title": "Agent Exchange Utility", "version": "1.0.0", "summary": "Pay-per-call US weather, US geocoding, RDAP, DNS, domain intel and verifiable random numbers, paid with x402 (USDC on Base). No API key.", "description": "9 GET routes. An unpaid request answers 402 with x402 requirements; sign an EIP-3009 USDC authorization for the amount to 0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c and resend with PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1). Bad parameters answer 400 before settlement; upstream failures after settlement answer 502 and replay once within 10 minutes.", "termsOfService": "https://utility.agentexchange.work/terms", "contact": { "name": "Agent Exchange", "url": "https://network.agentexchange.work" }, "x-guidance": "Prices (USD in USDC): /v1/weather/forecast 0.005, /v1/weather/hourly 0.005, /v1/weather/alerts 0.002, /v1/geo/geocode 0.005, /v1/geo/reverse 0.003, /v1/domain/rdap/:domain 0.005, /v1/dns/:domain 0.001, /v1/domain/:domain 0.01, /v1/fun/random 0.001. Read the free GET /samples/.json first to see real responses.", "x-payment": { "protocol": "x402", "versions": [ 1, 2 ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "facilitator": "https://facilitator.payai.network" } }, "servers": [ { "url": "https://utility.agentexchange.work" } ], "tags": [ { "name": "paid", "description": "x402-paid routes (USDC on Base)" }, { "name": "free", "description": "no payment" } ], "x-discovery": { "x402": "https://utility.agentexchange.work/.well-known/x402", "agent_card": "https://utility.agentexchange.work/.well-known/agent-card.json", "llms": "https://utility.agentexchange.work/llms.txt", "mcp": "https://utility.agentexchange.work/mcp", "ownershipProofs": [] }, "paths": { "/v1/weather/forecast": { "get": { "operationId": "weather_forecast", "summary": "Weather forecast (NWS, 7 days) ($0.005 USDC per call)", "description": "Returns the official US National Weather Service 7-day forecast for a US lat/lon as normalized JSON: about 14 day and night periods (temperature, precipitation probability, wind, short and detailed text), plus city, state, time zone, NWS office and grid. Call it when an agent needs a weather forecast for a US location. Points outside NWS coverage are refused with 400 before payment. Upstream: api.weather.gov points + gridpoint forecast; cached points 1 day, forecast 15 min. Free sample: https://utility.agentexchange.work/samples/weather-forecast.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "5000", "facilitator": "https://facilitator.payai.network" } } ] }, "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "latitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 38.8977 }, { "name": "lon", "in": "query", "required": true, "description": "longitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -77.0365 } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "city": { "type": "string" }, "state": { "type": "string" }, "timezone": { "type": "string" }, "grid": { "type": "object", "properties": { "office": { "type": "string" }, "x": { "type": "integer" }, "y": { "type": "integer" } } }, "forecast_zone": { "type": "string" }, "county_zone": { "type": "string" }, "radar_station": { "type": "string" } } }, "generated_at": { "type": "string" }, "updated_at": { "type": "string" }, "elevation_m": { "type": "number" }, "units": { "type": "string" }, "count": { "type": "integer" }, "periods": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "name": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "is_daytime": { "type": "boolean" }, "temperature": { "type": "integer" }, "temperature_unit": { "type": "string" }, "precip_probability_pct": { "type": "integer" }, "wind_speed": { "type": "string" }, "wind_direction": { "type": "string" }, "short_forecast": { "type": "string" }, "detailed_forecast": { "type": "string" }, "icon": { "type": "string" } } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "location": { "lat": 38.8977, "lon": -77.0365, "city": "Washington", "state": "DC", "timezone": "America/New_York", "grid": { "office": "LWX", "x": 97, "y": 71 }, "forecast_zone": "DCZ001", "county_zone": "DCC001", "radar_station": "KLWX" }, "generated_at": "2026-10-01T00:00:01+00:00", "updated_at": "2026-09-30T23:53:02+00:00", "elevation_m": 6.1, "units": "us", "count": 14, "periods": [ { "number": 1, "name": "Tonight", "start": "2026-09-30T20:00:00-04:00", "end": "2026-10-01T06:00:00-04:00", "is_daytime": false, "temperature": 62, "temperature_unit": "F", "precip_probability_pct": 0, "wind_speed": "6 mph", "wind_direction": "S", "short_forecast": "Mostly Cloudy", "detailed_forecast": "Mostly cloudy, with a low around 62. South wind around 6 mph.", "icon": "https://api.weather.gov/icons/land/night/bkn?size=medium" } ], "source": { "provider": "US National Weather Service (api.weather.gov)", "url": "https://api.weather.gov/gridpoints/LWX/97,71/forecast", "license": "public domain (work of the US Government); attribution appreciated: NOAA/National Weather Service" }, "fetched_at": "2026-10-01T00:12:01.000Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/weather/hourly": { "get": { "operationId": "weather_hourly", "summary": "Hourly weather, next 48 h (NWS) ($0.005 USDC per call)", "description": "Returns the next 48 hours of the official US National Weather Service hourly forecast for a US lat/lon as normalized JSON: per hour temperature, dew point, relative humidity, precipitation probability, wind and short text, plus location, time zone and NWS grid. Call it when an agent needs hour-by-hour weather for a US place. Points outside NWS coverage are refused with 400 before payment. Upstream: api.weather.gov points + gridpoint hourly forecast; cached points 1 day, hourly 10 min. Free sample: https://utility.agentexchange.work/samples/weather-hourly.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "5000", "facilitator": "https://facilitator.payai.network" } } ] }, "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "latitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 38.8977 }, { "name": "lon", "in": "query", "required": true, "description": "longitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -77.0365 } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "city": { "type": "string" }, "state": { "type": "string" }, "timezone": { "type": "string" }, "grid": { "type": "object", "properties": { "office": { "type": "string" }, "x": { "type": "integer" }, "y": { "type": "integer" } } }, "forecast_zone": { "type": "string" }, "county_zone": { "type": "string" }, "radar_station": { "type": "string" } } }, "generated_at": { "type": "string" }, "updated_at": { "type": "string" }, "elevation_m": { "type": "number" }, "units": { "type": "string" }, "count": { "type": "integer" }, "periods": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "start": { "type": "string" }, "end": { "type": "string" }, "is_daytime": { "type": "boolean" }, "temperature": { "type": "integer" }, "temperature_unit": { "type": "string" }, "precip_probability_pct": { "type": "integer" }, "dewpoint_c": { "type": "number" }, "relative_humidity_pct": { "type": "integer" }, "wind_speed": { "type": "string" }, "wind_direction": { "type": "string" }, "short_forecast": { "type": "string" }, "icon": { "type": "string" } } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "location": { "lat": 38.8977, "lon": -77.0365, "city": "Washington", "state": "DC", "timezone": "America/New_York", "grid": { "office": "LWX", "x": 97, "y": 71 }, "forecast_zone": "DCZ001", "county_zone": "DCC001", "radar_station": "KLWX" }, "generated_at": "2026-10-01T00:12:01+00:00", "updated_at": "2026-09-30T23:53:02+00:00", "elevation_m": 6.1, "units": "us", "count": 48, "periods": [ { "number": 1, "start": "2026-09-30T20:00:00-04:00", "end": "2026-09-30T21:00:00-04:00", "is_daytime": false, "temperature": 70, "temperature_unit": "F", "precip_probability_pct": 0, "dewpoint_c": 17.8, "relative_humidity_pct": 81, "wind_speed": "6 mph", "wind_direction": "S", "short_forecast": "Mostly Cloudy", "icon": "https://api.weather.gov/icons/land/night/bkn?size=small" } ], "source": { "provider": "US National Weather Service (api.weather.gov)", "url": "https://api.weather.gov/gridpoints/LWX/97,71/forecast/hourly", "license": "public domain (work of the US Government); attribution appreciated: NOAA/National Weather Service" }, "fetched_at": "2026-10-01T00:12:03.000Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/weather/alerts": { "get": { "operationId": "weather_alerts", "summary": "Active weather alerts (NWS) ($0.002 USDC per call)", "description": "Returns the active US National Weather Service watches, warnings and advisories for a point (?lat=&lon=) or a US state, territory or marine area code (?area=TX) as normalized JSON: event, severity, urgency, certainty, headline, area, onset and expiry, description, instructions and UGC/SAME codes. Call it when an agent must know whether severe weather affects a US place now. An empty list is a valid answer. Upstream: api.weather.gov/alerts/active; cached 60 s. Free sample: https://utility.agentexchange.work/samples/weather-alerts.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "2000", "facilitator": "https://facilitator.payai.network" } } ] }, "parameters": [ { "name": "lat", "in": "query", "required": false, "description": "latitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 29.7604 }, { "name": "lon", "in": "query", "required": false, "description": "longitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -95.3698 }, { "name": "area", "in": "query", "required": false, "description": "US state, territory or marine area code (instead of lat/lon)", "schema": { "type": "string", "enum": [ "AL", "AK", "AS", "AR", "AZ", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY", "MP", "PW", "FM", "MH", "AM", "AN", "GM", "LC", "LE", "LH", "LM", "LO", "LS", "PH", "PK", "PM", "PS", "PZ", "SL" ] }, "example": "TX" } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "area": { "type": "string" } } }, "title": { "type": "string" }, "updated": { "type": "string" }, "count": { "type": "integer" }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "headline": { "type": "string" }, "severity": { "type": "string" }, "certainty": { "type": "string" }, "urgency": { "type": "string" }, "status": { "type": "string" }, "message_type": { "type": "string" }, "category": { "type": "string" }, "response": { "type": "string" }, "area_desc": { "type": "string" }, "sent": { "type": "string" }, "effective": { "type": "string" }, "onset": { "type": "string" }, "expires": { "type": "string" }, "ends": { "type": "string" }, "sender_name": { "type": "string" }, "description": { "type": "string" }, "instruction": { "type": "string" }, "ugc_codes": { "type": "array", "items": { "type": "string" } }, "same_codes": { "type": "array", "items": { "type": "string" } } } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "query": { "area": "TX" }, "title": "Current watches, warnings, and advisories for Texas", "updated": "2026-10-01T00:10:10+00:00", "count": 1, "alerts": [ { "id": "urn:oid:2.49.0.1.840.0.961dd84f5243d34e5c565a5c4a62d8059a17b0a2.001.1", "event": "Severe Thunderstorm Warning", "headline": "Severe Thunderstorm Warning issued September 30 at 7:09PM CDT until September 30 at 8:00PM CDT by NWS San Angelo TX", "severity": "Severe", "certainty": "Observed", "urgency": "Immediate", "status": "Actual", "message_type": "Alert", "category": "Met", "response": "Shelter", "area_desc": "Callahan, TX; Jones, TX; Shackelford, TX; Taylor, TX", "sent": "2026-09-30T19:09:00-05:00", "effective": "2026-09-30T19:09:00-05:00", "onset": "2026-09-30T19:09:00-05:00", "expires": "2026-09-30T20:00:00-05:00", "ends": "2026-09-30T20:00:00-05:00", "sender_name": "NWS San Angelo TX", "description": "At 709 PM CDT, a severe thunderstorm was located near Impact, moving northeast at 30 mph. HAZARD...60 mph wind gusts.", "instruction": "For your protection move to an interior room on the lowest floor of a building.", "ugc_codes": [ "TXC059", "TXC253", "TXC417", "TXC441" ], "same_codes": [ "048059", "048253", "048417", "048441" ] } ], "source": { "provider": "US National Weather Service (api.weather.gov)", "url": "https://api.weather.gov/alerts/active?area=TX", "license": "public domain (work of the US Government); attribution appreciated: NOAA/National Weather Service" }, "fetched_at": "2026-10-01T00:12:04.000Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/geo/geocode": { "get": { "operationId": "geo_geocode", "summary": "US address geocode (Census) ($0.005 USDC per call)", "description": "Geocodes a US street address with the US Census Bureau Geocoder: returns the matched address, lat/lon and Census geographies (state and county FIPS, tract, block group, block, place, county subdivision, congressional district, ZCTA, metro area, school district). Call it when an agent needs coordinates or FIPS codes for a US address. A no-match answer (matched:false) is a valid, charged result; empty input is refused with 400 before payment. Upstream: geocoding.geo.census.gov onelineaddress (Public_AR_Current); cached 7 days. Free sample: https://utility.agentexchange.work/samples/geo-geocode.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "5000", "facilitator": "https://facilitator.payai.network" } } ] }, "parameters": [ { "name": "address", "in": "query", "required": true, "description": "one-line US street address: number, street, city, state and/or ZIP", "schema": { "type": "string", "minLength": 5, "maxLength": 200 }, "example": "1600 Pennsylvania Ave NW, Washington, DC 20500" } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "input_address": { "type": "string" }, "matched": { "type": "boolean" }, "count": { "type": "integer" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "matched_address": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "components": { "type": "object", "properties": { "zip": { "type": "string" }, "streetName": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "suffixType": { "type": "string" }, "suffixDirection": { "type": "string" }, "fromAddress": { "type": "string" }, "toAddress": { "type": "string" } } }, "tiger_line": { "type": "object", "properties": { "side": { "type": "string" }, "tigerLineId": { "type": "string" } } }, "geographies": { "type": "object", "properties": { "state": { "type": "object" }, "county": { "type": "object" }, "tract": { "type": "object" }, "block_group": { "type": "object" }, "block": { "type": "object" }, "place": { "type": "object" }, "county_subdivision": { "type": "object" }, "congressional_district": { "type": "object" }, "zcta": { "type": "object" }, "metro_area": { "type": "object" }, "school_district": { "type": "object" } } } } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "input_address": "1600 Pennsylvania Ave NW, Washington, DC 20500", "matched": true, "count": 1, "matches": [ { "matched_address": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "lat": 38.898703, "lon": -77.035189, "components": { "zip": "20500", "streetName": "PENNSYLVANIA", "city": "WASHINGTON", "state": "DC", "suffixType": "AVE", "suffixDirection": "NW", "fromAddress": "1600", "toAddress": "1648" }, "tiger_line": { "side": "L", "tigerLineId": "76225813" }, "geographies": { "state": { "fips": "11", "abbr": "DC", "name": "District of Columbia" }, "county": { "fips": "11001", "county_fips": "001", "name": "District of Columbia" }, "tract": { "geoid": "11001980000", "tract": "980000", "name": "Census Tract 9800" }, "block_group": { "geoid": "110019800001", "block_group": "1" }, "block": { "geoid": "110019800001034", "block": "1034", "layer": "2020 Census Blocks" }, "place": { "geoid": "1150000", "name": "Washington city" }, "county_subdivision": { "geoid": "1100150000", "name": "Washington city" }, "congressional_district": { "geoid": "1198", "name": "Delegate District (at Large)", "layer": "120th Congressional Districts" }, "zcta": { "zcta5": "20006" }, "metro_area": { "cbsa": "47900", "name": "Washington-Arlington-Alexandria, DC-VA-MD-WV Metro Area" }, "school_district": { "geoid": "1100030", "name": "District of Columbia Public Schools" } } } ], "source": { "provider": "US Census Bureau Geocoder (geocoding.geo.census.gov)", "url": "https://geocoding.geo.census.gov/geocoder/geographies/onelineaddress?address=...", "license": "public (US Government work); benchmark Public_AR_Current, vintage Current_Current" }, "fetched_at": "2026-10-01T00:12:05.000Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/geo/reverse": { "get": { "operationId": "geo_reverse", "summary": "Reverse geocode to Census geographies ($0.003 USDC per call)", "description": "Maps a lat/lon to US Census geographies with the US Census Bureau Geocoder: state and county FIPS, tract, block group, block, place, county subdivision, congressional district, ZCTA, metro area and school district. Call it when an agent has coordinates and needs the US county, FIPS codes or census tract. Points outside the US answer in_us:false (a valid, charged result). Upstream: geocoding.geo.census.gov geographies/coordinates; cached 7 days. Free sample: https://utility.agentexchange.work/samples/geo-reverse.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.003000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "3000", "facilitator": "https://facilitator.payai.network" } } ] }, "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "latitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 30.2672 }, { "name": "lon", "in": "query", "required": true, "description": "longitude in decimal degrees (WGS84)", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -97.7431 } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "in_us": { "type": "boolean" }, "geographies": { "type": "object", "properties": { "state": { "type": "object", "properties": { "fips": { "type": "string" }, "abbr": { "type": "string" }, "name": { "type": "string" } } }, "county": { "type": "object", "properties": { "fips": { "type": "string" }, "county_fips": { "type": "string" }, "name": { "type": "string" } } }, "tract": { "type": "object", "properties": { "geoid": { "type": "string" }, "tract": { "type": "string" }, "name": { "type": "string" } } }, "block_group": { "type": "object", "properties": { "geoid": { "type": "string" }, "block_group": { "type": "string" } } }, "block": { "type": "object", "properties": { "geoid": { "type": "string" }, "block": { "type": "string" }, "layer": { "type": "string" } } }, "place": { "type": "object", "properties": { "geoid": { "type": "string" }, "name": { "type": "string" } } }, "county_subdivision": { "type": "object", "properties": { "geoid": { "type": "string" }, "name": { "type": "string" } } }, "congressional_district": { "type": "object", "properties": { "geoid": { "type": "string" }, "name": { "type": "string" }, "layer": { "type": "string" } } }, "zcta": { "type": "object", "properties": { "zcta5": { "type": "string" } } }, "metro_area": { "type": "object", "properties": { "cbsa": { "type": "string" }, "name": { "type": "string" } } }, "school_district": { "type": "object", "properties": { "geoid": { "type": "string" }, "name": { "type": "string" } } } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "lat": 30.2672, "lon": -97.7431, "in_us": true, "geographies": { "state": { "fips": "48", "abbr": "TX", "name": "Texas" }, "county": { "fips": "48453", "county_fips": "453", "name": "Travis County" }, "tract": { "geoid": "48453001103", "tract": "001103", "name": "Census Tract 11.03" }, "block_group": { "geoid": "484530011032", "block_group": "2" }, "block": { "geoid": "484530011032007", "block": "2007", "layer": "2020 Census Blocks" }, "place": { "geoid": "4805000", "name": "Austin city" }, "county_subdivision": { "geoid": "4845390165", "name": "Austin CCD" }, "congressional_district": { "geoid": "4810", "name": "Congressional District 10", "layer": "120th Congressional Districts" }, "zcta": { "zcta5": "78701" }, "metro_area": { "cbsa": "12420", "name": "Austin-Round Rock-San Marcos, TX Metro Area" }, "school_district": { "geoid": "4808940", "name": "Austin Independent School District" } }, "source": { "provider": "US Census Bureau Geocoder (geocoding.geo.census.gov)", "url": "https://geocoding.geo.census.gov/geocoder/geographies/coordinates?x=-97.7431&y=30.2672&benchmark=Public_AR_Current&vintage=Current_Current&layers=all&format=json", "license": "public (US Government work); benchmark Public_AR_Current, vintage Current_Current" }, "fetched_at": "2026-10-01T00:12:05.851Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domain/rdap/{domain}": { "get": { "operationId": "domain_rdap", "summary": "RDAP domain registration ($0.005 USDC per call)", "description": "Looks up a domain in its registry's RDAP server (found through the IANA bootstrap) and returns normalized JSON: registered yes/no, registrar name and IANA id, creation, last-change and expiry dates, EPP status codes, nameservers and DNSSEC delegation (DS records). Call it for WHOIS-style questions: who is the registrar, when does it expire, is it registered. TLDs without RDAP are refused with 400 before payment. Upstream: data.iana.org/rdap/dns.json + registry RDAP; cached bootstrap 1 day, record 1 hour, not-found 15 min. Free sample: https://utility.agentexchange.work/samples/domain-rdap.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "5000", "facilitator": "https://facilitator.payai.network" } } ] }, "x-route-template": "/v1/domain/rdap/:domain", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "domain name (IDN accepted, converted to punycode)", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.-]+\\.[A-Za-z0-9-]+$", "maxLength": 253 }, "example": "example.com" } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "registered": { "type": "boolean" }, "ldh_name": { "type": "string" }, "unicode_name": { "type": [ "string", "number", "object", "null" ] }, "handle": { "type": "string" }, "registrar": { "type": "object", "properties": { "name": { "type": "string" }, "iana_id": { "type": "string" }, "abuse_email": { "type": [ "string", "number", "object", "null" ] }, "abuse_phone": { "type": [ "string", "number", "object", "null" ] }, "rdap_url": { "type": [ "string", "number", "object", "null" ] } } }, "created": { "type": "string" }, "updated": { "type": "string" }, "expires": { "type": "string" }, "rdap_database_updated": { "type": "string" }, "status": { "type": "array", "items": { "type": "string" } }, "nameservers": { "type": "array", "items": { "type": "string" } }, "dnssec": { "type": "object", "properties": { "signed": { "type": "boolean" }, "ds": { "type": "array", "items": { "type": "object", "properties": { "key_tag": { "type": "integer" }, "algorithm": { "type": "integer" }, "digest_type": { "type": "integer" }, "digest": { "type": "string" } } } } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "rdap_server": { "type": "string" }, "url": { "type": "string" }, "bootstrap": { "type": "string" }, "bootstrap_publication": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "domain": "example.com", "registered": true, "ldh_name": "example.com", "unicode_name": null, "handle": "2336799_DOMAIN_COM-VRSN", "registrar": { "name": "RESERVED-Internet Assigned Numbers Authority", "iana_id": "376", "abuse_email": null, "abuse_phone": null, "rdap_url": null }, "created": "1995-08-14T04:00:00Z", "updated": "2026-08-14T08:01:43Z", "expires": "2027-08-13T04:00:00Z", "rdap_database_updated": "2026-10-01T00:11:58Z", "status": [ "client delete prohibited", "client transfer prohibited", "client update prohibited" ], "nameservers": [ "elliott.ns.cloudflare.com", "hera.ns.cloudflare.com" ], "dnssec": { "signed": true, "ds": [ { "key_tag": 2371, "algorithm": 13, "digest_type": 2, "digest": "C988EC423E3880EB8DD8A46FE06CA230EE23F35B578D64E78B29C3E1C83D245A" } ] }, "source": { "provider": "RDAP (registry server named by the IANA bootstrap)", "rdap_server": "https://rdap.verisign.com/com/v1/", "url": "https://rdap.verisign.com/com/v1/domain/example.com", "bootstrap": "https://data.iana.org/rdap/dns.json", "bootstrap_publication": "2026-09-30T23:00:03Z", "license": "public registration data as published by the registry under ICANN RDAP policy" }, "fetched_at": "2026-10-01T00:12:09.422Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/dns/{domain}": { "get": { "operationId": "dns", "summary": "DNS lookup (DoH) ($0.001 USDC per call)", "description": "Resolves one DNS record type for a name through Cloudflare 1.1.1.1 DNS-over-HTTPS and returns normalized JSON: status (NOERROR, NXDOMAIN), DNSSEC-validated flag, answers with TTL and parsed fields (MX priority and host, joined TXT strings, CAA tag and value, SOA serial). ?type= is A (default), AAAA, MX, NS, TXT, CAA, SOA or CNAME. Call it when an agent needs a live DNS answer. NXDOMAIN is a valid answer. Upstream: cloudflare-dns.com/dns-query (application/dns-json); cached record TTL, 30-300 s. Free sample: https://utility.agentexchange.work/samples/dns.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "1000", "facilitator": "https://facilitator.payai.network" } } ] }, "x-route-template": "/v1/dns/:domain", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "domain name (IDN accepted, converted to punycode)", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+\\.[A-Za-z0-9-]+$", "maxLength": 253 }, "example": "example.com" }, { "name": "type", "in": "query", "required": false, "description": "record type", "schema": { "type": "string", "enum": [ "A", "NS", "CNAME", "SOA", "MX", "TXT", "AAAA", "CAA" ], "default": "A" }, "example": "MX" } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "rcode": { "type": "integer" }, "dnssec_validated": { "type": "boolean" }, "truncated": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "ttl": { "type": "integer" }, "data": { "type": "string" }, "parsed": { "type": "object", "properties": { "priority": { "type": "integer" }, "exchange": { "type": "string" }, "null_mx": { "type": "boolean" } } } } } }, "authority": { "type": "array" }, "resolver": { "type": "string" }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "url": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "name": "example.com", "type": "MX", "status": "NOERROR", "rcode": 0, "dnssec_validated": true, "truncated": false, "answers": [ { "name": "example.com", "type": "MX", "ttl": 267, "data": "0 .", "parsed": { "priority": 0, "exchange": ".", "null_mx": true } } ], "authority": [], "resolver": "Cloudflare 1.1.1.1 (cloudflare-dns.com DNS-over-HTTPS, JSON)", "source": { "provider": "Cloudflare DNS over HTTPS", "url": "https://cloudflare-dns.com/dns-query?name=example.com&type=MX" }, "fetched_at": "2026-10-01T00:12:12.643Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domain/{domain}": { "get": { "operationId": "domain", "summary": "Domain intel (RDAP + DNS + email auth) ($0.01 USDC per call)", "description": "One-record domain intelligence: RDAP summary (registrar, created, expiry, status, DNSSEC), DNS A, AAAA, CNAME, MX and NS, email authentication (SPF record and its all-qualifier, DMARC policy and reporting, MTA-STS presence, null MX), and a link to the domain's free Agent Exchange census record. Call it to vet a domain, a sender or a vendor in one request instead of eight lookups. Upstream: registry RDAP + cloudflare-dns.com DoH (8 queries); cached RDAP 1 hour, DNS by TTL. Free sample: https://utility.agentexchange.work/samples/domain.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "10000", "facilitator": "https://facilitator.payai.network" } } ] }, "x-route-template": "/v1/domain/:domain", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "domain name (IDN accepted, converted to punycode)", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.-]+\\.[A-Za-z0-9-]+$", "maxLength": 253 }, "example": "example.com" } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "exists_in_dns": { "type": "boolean" }, "rdap": { "type": "object", "properties": { "registered": { "type": "boolean" }, "registrar": { "type": "string" }, "registrar_iana_id": { "type": "string" }, "created": { "type": "string" }, "updated": { "type": "string" }, "expires": { "type": "string" }, "status": { "type": "array", "items": { "type": "string" } }, "nameservers": { "type": "array", "items": { "type": "string" } }, "dnssec_signed": { "type": "boolean" }, "rdap_url": { "type": "string" } } }, "dns": { "type": "object", "properties": { "a": { "type": "array", "items": { "type": "string" } }, "aaaa": { "type": "array", "items": { "type": "string" } }, "cname": { "type": "array" }, "mx": { "type": "array", "items": { "type": "object", "properties": { "priority": { "type": "integer" }, "exchange": { "type": "string" }, "null_mx": { "type": "boolean" } } } }, "ns": { "type": "array", "items": { "type": "string" } }, "dnssec_validated": { "type": "boolean" }, "status": { "type": "string" } } }, "email_auth": { "type": "object", "properties": { "spf": { "type": "object", "properties": { "present": { "type": "boolean" }, "record": { "type": "string" }, "all": { "type": "string" }, "multiple_records": { "type": "boolean" } } }, "dmarc": { "type": "object", "properties": { "present": { "type": "boolean" }, "record": { "type": "string" }, "policy": { "type": "string" }, "subdomain_policy": { "type": "string" }, "pct": { "type": [ "string", "number", "object", "null" ] }, "rua": { "type": [ "string", "number", "object", "null" ] }, "ruf": { "type": [ "string", "number", "object", "null" ] }, "multiple_records": { "type": "boolean" } } }, "mta_sts": { "type": "object", "properties": { "present": { "type": "boolean" } } }, "null_mx": { "type": "boolean" } } }, "census": { "type": "object", "properties": { "url": { "type": "string" }, "note": { "type": "string" } } }, "sources": { "type": "object", "properties": { "rdap": { "type": "string" }, "dns": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "domain": "example.com", "exists_in_dns": true, "rdap": { "registered": true, "registrar": "RESERVED-Internet Assigned Numbers Authority", "registrar_iana_id": "376", "created": "1995-08-14T04:00:00Z", "updated": "2026-08-14T08:01:43Z", "expires": "2027-08-13T04:00:00Z", "status": [ "client delete prohibited", "client transfer prohibited", "client update prohibited" ], "nameservers": [ "elliott.ns.cloudflare.com", "hera.ns.cloudflare.com" ], "dnssec_signed": true, "rdap_url": "https://rdap.verisign.com/com/v1/domain/example.com" }, "dns": { "a": [ "104.18.26.120", "104.18.27.120" ], "aaaa": [ "2606:4700::6812:1a78", "2606:4700::6812:1b78" ], "cname": [], "mx": [ { "priority": 0, "exchange": ".", "null_mx": true } ], "ns": [ "elliott.ns.cloudflare.com", "hera.ns.cloudflare.com" ], "dnssec_validated": true, "status": "NOERROR" }, "email_auth": { "spf": { "present": true, "record": "v=spf1 -all", "all": "-all", "multiple_records": false }, "dmarc": { "present": true, "record": "v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s", "policy": "reject", "subdomain_policy": "reject", "pct": null, "rua": null, "ruf": null, "multiple_records": false }, "mta_sts": { "present": false }, "null_mx": true }, "census": { "url": "https://network.agentexchange.work/v1/access/example.com.json", "note": "free record from the Agent Exchange web censuses (security.txt, accessibility, AI-crawler rules) if this domain is in one; not fetched here and may answer 404" }, "sources": { "rdap": "https://rdap.verisign.com/com/v1/domain/example.com", "dns": "Cloudflare 1.1.1.1 DNS over HTTPS (cloudflare-dns.com, JSON)" }, "fetched_at": "2026-10-01T00:12:20.000Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fun/random": { "get": { "operationId": "fun_random", "summary": "Verifiable random integers (drand) ($0.001 USDC per call)", "description": "Returns n random integers between min and max derived from the latest public drand randomness beacon round (League of Entropy), with the round number, signature, randomness and the exact SHA-256 derivation so anyone can reproduce and audit the numbers. Call it for dice, raffles, lotteries, sampling or game moves that must be provably unmanipulated. Optional salt makes results distinct per caller. Upstream: api.drand.sh (default chain, 30 s rounds); cached until the next round (at most 30 s). Free sample: https://utility.agentexchange.work/samples/fun-random.json", "tags": [ "paid" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [ { "x402": { "version": 2, "versions": [ 1, 2 ], "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "amount_atomic": "1000", "facilitator": "https://facilitator.payai.network" } } ] }, "parameters": [ { "name": "min", "in": "query", "required": false, "description": "smallest value (inclusive)", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "max", "in": "query", "required": false, "description": "largest value (inclusive)", "schema": { "type": "integer", "default": 100 }, "example": 6 }, { "name": "n", "in": "query", "required": false, "description": "how many integers", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "example": 2 }, { "name": "salt", "in": "query", "required": false, "description": "optional caller salt mixed into the derivation", "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]*$" }, "example": "game-42" } ], "responses": { "200": { "description": "Result", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 settlement receipt {success, transaction, network, payer}" }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "integer" } }, "min": { "type": "integer" }, "max": { "type": "integer" }, "n": { "type": "integer" }, "salt": { "type": "string" }, "drand": { "type": "object", "properties": { "chain_hash": { "type": "string" }, "public_key": { "type": "string" }, "scheme": { "type": "string" }, "period_s": { "type": "integer" }, "genesis_time": { "type": "integer" }, "round": { "type": "integer" }, "round_time": { "type": "string" }, "randomness": { "type": "string" }, "signature": { "type": "string" }, "previous_signature": { "type": "string" }, "url": { "type": "string" } } }, "checks": { "type": "object", "properties": { "randomness_is_sha256_of_signature": { "type": "boolean" } } }, "derivation": { "type": "object", "properties": { "method": { "type": "string" } } }, "source": { "type": "object", "properties": { "provider": { "type": "string" }, "license": { "type": "string" } } }, "fetched_at": { "type": "string" } } }, "example": { "values": [ 4, 2 ], "min": 1, "max": 6, "n": 2, "salt": "", "drand": { "chain_hash": "8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce", "public_key": "868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31", "scheme": "pedersen-bls-chained", "period_s": 30, "genesis_time": 1595431050, "round": 6512750, "round_time": "2026-10-01T00:12:00.000Z", "randomness": "07940a2473df0f12cb2233eb3422e233eeb43ddddabff8a454a6fff4b88d4159", "signature": "98a9c5db6e0a913ce1ff2af62ca71a39ceb1f79302ded4faa356775437ea664d450809145fe00a8c6bedee943a2dfad70254b79734a2a5d71269e9b9f4798ab236fcb3463ad53c244ec302842259a5e99b4097e9345afc282f634ea2ac48e663", "previous_signature": "85ebe51c8b933063fdd433a95a3730170c5ac1072ac291ebfe502231e127c6d25179805a219c1999f379c2ee45629c260be71e58395e4944180746f5096d53a661e574e7b2672df188c8548c7d09bf39e84017207b85ce7a8c6516fabd00a891", "url": "https://api.drand.sh/8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce/public/6512750" }, "checks": { "randomness_is_sha256_of_signature": true }, "derivation": { "method": "rejection sampling over SHA-256" }, "source": { "provider": "drand randomness beacon, League of Entropy (api.drand.sh)", "license": "public beacon output" }, "fetched_at": "2026-10-01T00:12:14.882Z" } } } }, "400": { "description": "Invalid parameters (or outside coverage); nothing verified or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v2 envelope in the JSON body and, base64, in the PAYMENT-REQUIRED header (accepts[0] is Base USDC exact).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 of the same JSON as the body" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "409": { "description": "Payment nonce already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 unpaid requests per minute from this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failed after settlement (code upstream_failed); resend with the same payment header once within 10 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream unavailable before payment; nothing settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/samples": { "get": { "operationId": "samples", "summary": "index of real sample responses (JSON)", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/live.json": { "get": { "operationId": "live_json", "summary": "per-route counters: 402s served, paid calls, successes, failures (JSON)", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "service health (JSON)", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi_json", "summary": "OpenAPI 3.1 with x-payment-info on each paid operation", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/x402": { "get": { "operationId": "well_known_x402", "summary": "x402 manifest: every paid route with the same prices as the 402s", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/agent-card.json": { "get": { "operationId": "well_known_agent_card_json", "summary": "A2A agent card, one skill per route", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/llms.txt": { "get": { "operationId": "llms_txt", "summary": "this service for language models", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP Streamable HTTP endpoint (JSON-RPC 2.0 over POST): tools/list, tools/call; utility_pricing is free", "tags": [ "free" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/samples/{route}.json": { "get": { "operationId": "sample", "summary": "one real sample response for a paid route", "tags": [ "free" ], "security": [], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "weather-forecast", "weather-hourly", "weather-alerts", "geo-geocode", "geo-reverse", "domain-rdap", "dns", "domain", "fun-random" ] } } ], "responses": { "200": { "description": "Sample", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error", "code", "status", "request_id" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "snake_case, e.g. invalid_param, outside_coverage, upstream_failed, nonce_replay, rate_limited" }, "status": { "type": "integer" }, "hint": { "type": "string" }, "settled": { "type": "boolean" }, "docs": { "type": "string" }, "request_id": { "type": "string" } } }, "PaymentRequired": { "type": "object", "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "iconUrl": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object" } } } }, "extensions": { "type": "object" }, "message": { "type": "string" }, "price": { "type": "string" } } } } } }