Explore›Agents

PUBLIC MACHINE INTERFACE

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.

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.

MCP V1

The stateless MCP endpoint supports discovery, x402 challenge preparation, externally signed paid execution, and purchase-scoped recovery.

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

MCP endpoint

The external MCP path is Production-verified for discovery, external signing, Arc Mainnet settlement, paid execution, persistent recovery, same-authorization replay without duplicate settlement or provider execution, and buyer, seller, and platform accounting. Browser and UI flows were not part of that verification.

https://mahshar.xyz/api/mcp

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.

The MCP client first calls execute_api_call without a signature, validates the real x402 challenge, and signs externally. Mahshar never accepts private keys, signs automatically, or takes custody. The client then resubmits the exact arguments with the prepared-call token and signature. A paid response reports its delivery state and retryability; get_purchase_response uses the returned purchase capability for exact-purchase recovery.

mcp POST /api/mcp (stateless) tools search_apis, get_api execute_api_call get_purchase_response path GET|POST /api/proxy/{api_id} envelope POST /api/proxy retrieve GET /api/calls/last-response signing external wallet only

Continue with the human-readable documentation.

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

Open documentation