Agent API

Lens AI exposes a pay-per-call trust and ecosystem API any agent can query. It is self-describing, priced over x402, and settled in USDC on Arc mainnet. Eligible builders whose project data grounds a response may receive a small USDC recognition payment.

Base URL https://arclenz.xyz/api · Protocol x402 · Network Arc · Token USDC

Manifest

GET /api/agent

Free and unauthenticated. Returns the service description, price, payment header, and available actions — everything an agent needs to discover and use the API.

curl https://arclenz.xyz/api/agent

{
  "name": "Lens AI",
  "summary": "Pay-per-call trust & ecosystem intelligence for Arc, settled in USDC…",
  "protocol": "x402",
  "network": "Arc",
  "token": "USDC",
  "price": "$0.0010",
  "price_e6": 1000,
  "pay_header": "payment-signature",
  "actions": {
    "trust":    { "description": "Trust verdict for a project on Arc." },
    "discover": { "description": "Find Arc projects, optionally trusted-only." },
    "project":  { "description": "A project's live metrics + trust standing." }
  }
}

Payment & authentication

POST /api/agent

All actions are pay-per-call. Send the signed x402 payment payload in the payment-signature header. Until a valid payment arrives, the endpoint returns 402 Payment Required with a PAYMENT-REQUIRED challenge header.

Header	Required	Description
`payment-signature`	✓	The signed x402 payment payload produced by a compatible client after receiving the payment challenge.
`x-agent-id`		Optional caller identity, used for per-caller de-duplication of builder payouts (24h).
`content-type`	✓	`application/json`

A 402 response looks like this:

HTTP/1.1 402 Payment Required
x-payment-price: $0.0010
x-payment-token: USDC
x-payment-network: Arc
 
{ "error": "Payment required — this is a pay-per-call service.",
  "code": "payment_required", "price": "$0.0010", ... }

Production does not accept demo payment proofs. The action runs only after its x402 payment has been verified and settled.

Actions

Returns a trust verdict for a single project on Arc.

Parameter	Type	Required	Description
`action`	string	✓	`"trust"`
`target`	string	✓	Project name or slug (fuzzy-matched against live projects).

curl -X POST https://arclenz.xyz/api/agent \
  -H "content-type: application/json" \
  -H "payment-signature: <x402 payment signature>" \
  -d '{"action":"trust","target":"lunex"}'

{
  "action": "trust",
  "result": { "found": true, "name": "Lunex", "slug": "lunex", "trust": "Established" },
  "paid_to_builders": [
    { "project": "Lunex", "amount": "$0.0008", "trust": "Established", "tx": "0x1266259f…2b791f74" }
  ],
  "settled_on": "Arc"
}

Finds projects on Arc, optionally filtered by category and restricted to trusted projects only.

Parameter	Type	Required	Description
`action`	string	✓	`"discover"`
`category`	string		Optional category filter (e.g. `"DEX"`).
`trusted_only`	boolean		When true, returns only Verified / Established / Partner / Official projects.
`limit`	number		1–20, default 8.

curl -X POST https://arclenz.xyz/api/agent \
  -H "content-type: application/json" \
  -H "payment-signature: <x402 payment signature>" \
  -d '{"action":"discover","trusted_only":true,"limit":5}'

{
  "action": "discover",
  "result": {
    "count": 5,
    "projects": [
      { "name": "Lunex", "slug": "lunex", "category": "DEX", "tagline": "…", "trust": "Established" }
    ]
  },
  "paid_to_builders": [ ],
  "settled_on": "Arc"
}

Returns a single project’s live metrics plus its trust standing.

Parameter	Type	Required	Description
`action`	string	✓	`"project"`
`name`	string	✓	Project name or slug.

curl -X POST https://arclenz.xyz/api/agent \
  -H "content-type: application/json" \
  -H "payment-signature: <x402 payment signature>" \
  -d '{"action":"project","name":"lunex"}'

{
  "action": "project",
  "result": {
    "found": true, "name": "Lunex", "slug": "lunex", "category": "DEX",
    "trust": "Established", "tvl": "$1.2M", "volume": "$4.8M", "revenue": "$12K"
  },
  "paid_to_builders": [ ],
  "settled_on": "Arc"
}

Additional actions

Action	Purpose	Required input	Price
`metrics`	Returns available verified metrics and recent history for one project.	`name`; optional `days` from 7 to 90	Current manifest base price
`risk`	Returns ArcLens trust standing and available contract or website risk signals.	`name`	Current manifest base price
`ask`	Returns a full Lens AI answer grounded in ArcLens data and the Arc knowledge base.	`question`, maximum 500 characters	Published in the live manifest

Always read GET /api/agent before paying. The live manifest is the source of truth for current actions and prices.

Response fields

Field	Description
`action`	The action that was executed.
`result`	The action’s payload (see each action above).
`paid_to_builders`	Builders funded by this call: `project`, `amount`, `trust`, and the on-chain `tx`. Empty when no trusted builder matched or the caller already funded that builder within 24h.
`settled_on`	Always `"Arc"`.

Errors & rate limits

Status	Meaning
`400`	Malformed JSON, or an unknown action. The manifest is included in the body.
`402`	No valid payment proof. Price is returned in the `x-payment-*` headers.
`429`	Rate limit or daily capacity reached. Respect `Retry-After` when present.
`500`	Unexpected failure. Safe to retry with backoff.

Rate limit: 30 requests per minute per caller. Verify any payout by opening its tx on the explorer: arclenz.xyz/tx/<hash>.

The nanopayment economy For builders