Skip to main content
The gateway is Molpha’s HTTP entry point. It authenticates the caller, checks the subscription or the x402 payment, stamps the round’s timestamp, dispatches the round to the selected nodes and returns the signed attestation. Gateways are operated by Molpha and registered on-chain by the protocol authority. Most integrations use the gateway through the SDK or MCP. Use the HTTP API directly when you work in another language or need full control.

​
Base URL

​
Endpoints

​
Requests

A round request names a source by its apiConfig, a quorum (signaturesRequired) and the current registryVersion. You never send a sourceId or a timestamp:
  • The gateway, SDK and nodes each derive the sourceId from the apiConfig. See Source ID.
  • The gateway stamps the round on a 100 ms grid after admitting it. See Round timing.
  • registryVersion must equal the current on-chain version; a stale one gets 400.

​
Authentication

​
RequestAuth

POST /v1/round/execute carries subscriptionOwner, consumerAuthority (the owner itself or one of its delegates), authTimestamp and authSig, an Ed25519 signature over:
authTimestamp is unix seconds, and the gateway rejects it with 401 when it is further from its clock than requestAuthWindowSeconds (see /v1/info; 60 on devnet). Sign a fresh one for every request. RequestAuth only authorizes use of the subscription: it is not part of the round, the signed message or any payment.

​
Sign-in sessions

Instead of RequestAuth, a caller can sign in once and send Authorization: Bearer <token>. Sessions are available when GET /v1/info reports sessionAuth: true.
  1. GET /v1/session/challenge?address=<wallet>[&owner=<owner>] returns the Sign-In-With-X message (data.message) and its terms (data.info).
  2. Sign the message’s UTF-8 bytes with the wallet (Ed25519).
  3. POST /v1/session with a SIGN-IN-WITH-X header: base64 JSON of the info fields plus address, chainId, type: "ed25519", signatureScheme: "siws" and the base58 signature. It answers 201 with data.token and data.expiresAt.
  4. Send Authorization: Bearer <token> on POST /v1/round/execute, with no authSig or authTimestamp.
  5. DELETE /v1/session signs out.
A token is valid only at the gateway that issued it, for 30 minutes by default and never past the subscription term. It identifies the caller only: the subscription and delegate are checked against chain state (cached for a few seconds) on every round. The hosted MCP server wraps this flow.

​
x402

POST /v1/x402/execute takes no RequestAuth: the payment is the authorization. See x402 pay-per-request.

​
Admission

  • Subscription rounds need an active subscription, a quorum within the plan’s max_signers, and remaining quota. Quota is counted per 30-day term across the owner and its delegates, and a delegate’s rounds also count against its own max_data_requests. A round that fails before completing gives its unit back.
  • x402 rounds need a verified payment of the quoted price to the protocol treasury.
  • The Solana program does not settle rounds individually; the gateway enforces payment and quota at admission.

​
Response

Both execute endpoints return 200 with data.attestation:
  • payload: value, sourceId, registryVersion, signaturesRequired, timestamp (unix ms)
  • signature: signature, commitment, signersBitmap
plus a decimal value, fresh, and, in tolerance mode, aggregation. The x402 endpoint also returns a PAYMENT-RESPONSE header. Field meanings are in Rounds and attestations.
A gateway response is not proof of anything on its own. Verify the attestation before you act on it: see the consumer checklist.

​
Status codes

409, 429 and capacity 503s are returned before anything is reserved or spent. Any other retry is a new round that spends quota or a payment again.