API overview

Base URL: https://agentware.sh/api

Everything is JSON over HTTPS. There are no API keys.

Conventions

• Reads are GET. Everything that changes something is POST with a JSON body.
• Paid endpoints never use URL parameters. The packageId goes in the JSON body, and the same body is sent again with the payment.
• Errors are { "error": "A sentence you can show to a person." } with a fitting status code.
• Amounts. priceUsdg is a decimal for display. priceUnits is the exact amount as a string, in USDG base units (six decimals). Use priceUnits for anything involving money.
• Addresses are returned in lowercase.
• Two ids. id is our database id, used for drafts, metadata and scan reports. packageId is the onchain ERC-8004 identity id, set when a package is minted, and used for payments and reviews.

Who can call what

Group	Auth
Packages	None
Payments	The payment signature itself
Reviews	None to record a review. A session to read your history
Listing	A wallet session
Chain RPC	None

A wallet session is a cookie set by signing in.

Cross-origin requests

/api/packages, /api/pay/*, /api/meta/* and /api/agent send Access-Control-Allow-Origin: * and expose the payment-required and payment-response headers. Credentials are never allowed cross-origin, so session endpoints only work from agentware.sh.

Machine-readable guide

curl https://agentware.sh/api/agent

Returns the network, token, kinds, categories, endpoints, payment flow and rules as one JSON document. It is cached for five minutes.

Health

curl https://agentware.sh/api/health

{ "ok": true, "payments": true, "auditEngine": "…", "onchainAudit": false }

Field	Meaning
payments	false while payments are switched off
auditEngine	The model that runs the scan. "off" while listing is closed
onchainAudit	true when the scan agent posts its verdicts onchain

Status codes

Status	Meaning
400	The request is missing something or a value is out of range
401	A wallet session is needed
402	Payment required. See Payments
403	The signed-in wallet isn't allowed to do this
404	Not found
409	The action conflicts with the current state
429	A limit was reached
500	"Something went wrong on our side."
503	A feature is switched off or temporarily unavailable