Agent-ready API access,defined by a public contract.

Mahshar exposes active API listings, request contracts, payment requirements, and proxy execution details through its discovery endpoint and OpenAPI document.

View raw discovery JSON Read integration guide

PUBLIC CONTRACT

What the current agent interface exposes

Each capability below is present in the discovery route, OpenAPI contract, proxy implementation, or purchase-access flow.

Machine-readable discovery

The discovery endpoint returns active listings with methods, proxy URLs, request metadata, prices, and response contracts.

Two proxy styles

Listings declare either a direct path route for matching GET or POST calls, or the envelope route for GET, POST, PUT, and DELETE.

Arc Mainnet x402

Paid calls use x402 v2 payment requirements for Arc Mainnet and settle against the payment terms returned by the 402 challenge.

Purchase access

Paid responses include a purchase capability that can retrieve only the private response for that exact purchase.

REQUEST FLOW

How an agent calls a listed API

The public contract describes the full sequence from catalog selection through paid execution.

Discover

Fetch active listings from /api/agent/discover and follow its pagination contract.

Inspect

Use the listing method, proxy style, request metadata, schemas when present, and advertised price.

Authorize payment

Probe without a payment signature, validate the returned Arc Mainnet x402 v2 requirement, then sign its authorization.

Execute and retain access

Replay the identical request with the payment signature and persist the returned purchase-access capability.

DEVELOPER RESOURCES

Use the existing contracts and examples

These destinations are implemented routes or files in the Mahshar repository.

Public API marketplace

Browse crawlable pages for active APIs before using the machine contract to execute a call.

Browse APIs

Raw machine discovery

View the public JSON catalog consumed by agents. This is machine data, not a product page.

View raw discovery JSON

OpenAPI 3.1 specification

Inspect the public discovery, execution, access, and recovery contract.

Open OpenAPI specification

Integration guide

Follow the documented discovery, payment, delivery-state, and recovery sequence.

Read guide

Client example

The repository client covers discovery, probes, signing, execution, retrieval, and replay checks.

scripts/mahshar-agent-client.mts

E2E harness

The repository harness has a dry run that fetches discovery and OpenAPI without signing or sending a payment.

scripts/mahshar-agent-e2e.mts

DELIVERY & RECOVERY

Retry behavior is declared, not guessed.

A paid response reports its delivery state and retryability. The integration guide permits replay of the exact proof and request only when the response marks it retryable. The reconciliation route finalizes durable accounting only; it does not settle again or execute the upstream API.

discovery  GET  /api/agent/discover
spec       GET  /api/openapi
path       GET|POST /api/proxy/{api_id}
envelope   POST /api/proxy
retrieve   GET  /api/calls/last-response
reconcile  POST /api/payments/reconcile

Continue with the human-readable documentation.

Review the public contract, payment sequence, access model, and recovery rules in one place.

Open documentation