Machine-readable discovery
The discovery endpoint returns active listings with methods, proxy URLs, request metadata, prices, and response contracts.
PUBLIC MACHINE INTERFACE
Mahshar exposes active API listings, request contracts, payment requirements, and proxy execution details through its discovery endpoint and OpenAPI document.
PUBLIC CONTRACT
Each capability below is present in the discovery route, OpenAPI contract, proxy implementation, or purchase-access flow.
The discovery endpoint returns active listings with methods, proxy URLs, request metadata, prices, and response contracts.
The stateless MCP endpoint supports discovery, x402 challenge preparation, externally signed paid execution, and purchase-scoped recovery.
Listings declare either a direct path route for matching GET or POST calls, or the envelope route for GET, POST, PUT, and DELETE.
Paid calls use x402 v2 payment requirements for Arc Mainnet and settle against the payment terms returned by the 402 challenge.
Paid responses include a purchase capability that can retrieve only the private response for that exact purchase.
REQUEST FLOW
The public contract describes the full sequence from catalog selection through paid execution.
Fetch active listings from /api/agent/discover and follow its pagination contract.
Use the listing method, proxy style, request metadata, schemas when present, and advertised price.
Probe without a payment signature, validate the returned Arc Mainnet x402 v2 requirement, then sign its authorization.
Replay the identical request with the payment signature and persist the returned purchase-access capability.
DEVELOPER RESOURCES
These destinations are implemented routes or files in the Mahshar repository.
Browse crawlable pages for active APIs before using the machine contract to execute a call.
Browse APIsThe 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/mcpView the public JSON catalog consumed by agents. This is machine data, not a product page.
View raw discovery JSONInspect the public discovery, execution, access, and recovery contract.
Open OpenAPI specificationFollow the documented discovery, payment, delivery-state, and recovery sequence.
Read guideThe repository client covers discovery, probes, signing, execution, retrieval, and replay checks.
scripts/mahshar-agent-client.mtsThe repository harness has a dry run that fetches discovery and OpenAPI without signing or sending a payment.
scripts/mahshar-agent-e2e.mtsDELIVERY & RECOVERY
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 onlyReview the public contract, payment sequence, access model, and recovery rules in one place.