Explore›Docs

MAHSHAR DOCUMENTATION

Documentation for theinterfaces that exist today.

Start with the marketplace, provider onboarding, agent discovery, Arc Mainnet x402 contract, purchase access, or Wallet funding flow.

GETTING STARTED

Three implemented entry points

Mahshar provides separate interfaces for people buying API calls, providers listing endpoints, and autonomous clients.

Buy API access

Browse active APIs on the public Marketplace, then open the existing buyer application when you are ready to connect a wallet and make a call.

List an API

The provider keeps operating the upstream service. Mahshar collects the endpoint, request contract, authentication mode, public metadata, and listed base price for its separate listing and access path.

  • Buyers currently pay the listed base price plus 10%; the seller share is 90% of the listed base price.
  • Buyer and seller amounts are calculated independently and rounded to the nearest micro-USDC (0.000001 USDC), so extremely small prices can produce small effective-percentage differences.
  • The current listing path has no listing, publication, or subscription fee.
  • Seller shares become withdrawable after durable paid-call accounting. The minimum withdrawal is 1 USDC, and estimated Arc gas is deducted from the requested amount.
  • Analyze sends a representative request. Publish checks the persisted endpoint configuration again before activation.
  • The provider remains responsible for upstream availability, quota, and capacity.

Integrate an agent

The agent path starts with the public discovery endpoint, which links the OpenAPI contract and describes each active listing.

AGENT INTEGRATION

Discover first, then follow the selected listing.

The discovery response includes the listing method, proxy URL and style, request metadata, optional schemas and examples, auth type, listed price, payment contract, and response wrapper. Seller upstream URLs and credentials are not part of that public contract.

GET /api/agent/discover → active listings → proxy_url + proxy_style → request + response metadata → Arc Mainnet payment contract → OpenAPI URL GET /api/openapi → application/yaml

MCP V1 PHASE 2

Discovery and externally signed x402 execution through one stateless endpoint.

Connect an MCP client to https://mahshar.xyz/api/mcp. search_apis and get_api use the safe public discovery contract. An unsigned execute_api_call returns the real 402 challenge and a short-lived prepared-call token; the MCP host must validate the challenge and sign it with its own wallet before replaying the exact prepared arguments. Mahshar never accepts private keys, signs automatically, or takes custody. get_purchase_response retrieves one exact paid response using the returned bearer purchase capability. 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.

endpoint POST https://mahshar.xyz/api/mcp transport stateless Streamable HTTP tools search_apis, get_api execute_api_call get_purchase_response signing external wallet required custody none recovery returned purchase capability

PAYMENT, AUTH & ACCESS

The current request contract

These behaviors are declared in the proxy routes, agent discovery response, OpenAPI document, and purchase-access implementation.

x402 v2 payment

  • Probe the intended request without Payment-Signature.
  • Read the base64 PAYMENT-REQUIRED header from the 402 response.
  • Validate and sign the offered Arc Mainnet requirement, then retry the identical request.

Seller endpoint authentication

  • Listings can declare public, API-key, bearer, or query-parameter authentication.
  • Credentials are encrypted with AES-256-GCM before database storage, omitted from public discovery and buyer-facing listing data, and not returned to the provider after storage.
  • Mahshar decrypts a configured credential server-side only where analysis, verification, or proxy execution requires it; buyer-supplied headers are not forwarded upstream.

Purchase access and recovery

  • Paid results include a purchase-access capability for response retrieval.
  • Only a response marked retryable permits an exact proof and request replay.
  • Accounting reconciliation never resettles payment or re-executes the upstream request.

Need help with a product flow?

Use the self-service support topics or contact the verified Mahshar support address.

Go to Support