> ## Documentation Index > Fetch the complete documentation index at: https://docs.molpha.io/llms.txt > Use this file to discover all available pages before exploring further. # Execute an x402 pay-per-request round > x402 v2 exact Solana payment to the protocol treasury; no subscription required. ## OpenAPI ````yaml gateway-openapi.yaml POST /v1/x402/execute openapi: 3.1.0 info: contact: {} description: HTTP entry point to the Molpha oracle protocol. title: Molpha Gateway API version: '1.0' x-mint: metadata: description: >- Dispatch oracle rounds, collect threshold signatures, and return payloads for Solana, EVM, and Starknet verification. servers: - url: https://gateway.molpha.io description: Devnet (SDK default) security: [] tags: - name: health x-group: Health description: Liveness probes - name: gateway x-group: Gateway description: Gateway identity and the RequestAuth window - name: nodes x-group: Nodes description: Oracle node discovery - name: providers x-group: Providers description: Integrated data providers - name: round x-group: Subscription rounds description: Subscription and delegate execute path - name: session x-group: Sessions description: >- Sign-In-With-X sessions (served when `GET /v1/info` reports `sessionAuth` true) - name: x402 x-group: x402 pay-per-request description: >- Pay-per-request path paid in USDC to the protocol treasury (requires a configured facilitator) paths: /v1/x402/execute: post: tags: - x402 summary: Execute an x402 pay-per-request round description: >- x402 v2 exact Solana payment to the protocol treasury; no subscription required. parameters: - name: PAYMENT-SIGNATURE in: header required: false description: >- Base64 x402 v2 payment payload. Omit on the first request to receive the `402` requirements. schema: type: string requestBody: required: true description: x402 execute request content: application/json: schema: $ref: '#/components/schemas/X402ExecuteRequest' example: signatures_required: 3 registry_version: 42 apiConfig: url: https://api.example.com/v1/price method: GET headers: {} responseParser: $.data.price valueTransform: multiply:1e6 responses: '200': description: Signed aggregate; the payment is confirmed headers: PAYMENT-RESPONSE: description: Base64 x402 v2 settlement receipt schema: type: string content: application/json: schema: $ref: '#/components/schemas/AttestationResponse' '400': description: Validation failure or stale `registry_version` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: >- Payment missing or rejected, or the API source is paywalled (`extensions.upstream` carries the quote) headers: PAYMENT-REQUIRED: description: Base64 x402 v2 payment requirements schema: type: string content: application/json: schema: $ref: '#/components/schemas/PaymentRequiredResponse' '409': description: >- Duplicate round identity (this payer already has a round for this source and quorum in the same 100 ms tick; nothing was reserved and an unused authorization stays usable; retry after one tick) or the payment authorization was already used for a round. No `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- x402 or facilitator unavailable, uncertain payment outcome, gateway at its concurrency limit (with `Retry-After`; payment not reserved), too few nodes accepting the round, node round timeout or upstream failure (the authorization is spent unsettled; retry with a new payment), or the gateway's sponsored provider access at its call limit (the payment is not settled and can be reused) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: X402ExecuteRequest: type: object description: >- Request body for `POST /v1/x402/execute`. It carries no timestamp and no payer, amount, signature or payment reference; payment is in `PAYMENT-SIGNATURE`. required: - signatures_required - registry_version - apiConfig properties: signatures_required: type: integer description: >- Requested quorum for this round. Must be at least protocol `min_signers` and at most the current node count. example: 3 registry_version: type: integer description: Active on-chain registry version. Must match the current version. example: 42 apiConfig: $ref: '#/components/schemas/ApiConfigRequest' encKeyBundle: $ref: '#/components/schemas/EncKeyBundleRequest' sourcePayments: type: array description: >- Base64 x402 payloads for a paywalled API source, one per node in the round's eligible set. They pay the source, never Molpha. items: type: string x402Source: type: boolean description: >- Declare a paywalled API source to be quoted in `extensions.upstream` before running the round. AttestationResponse: type: object description: >- Successful round response, shared by `POST /v1/round/execute` and `POST /v1/x402/execute`. The attestation payload and Schnorr signature are what verifiers consume. properties: status: type: string example: completed data: $ref: '#/components/schemas/AttestationData' ErrorResponse: type: object properties: error: type: string description: Human-readable error message. example: validation failed PaymentRequiredResponse: type: object description: >- x402 v2 payment requirements, returned with `402` and base64-encoded in the `PAYMENT-REQUIRED` header. properties: x402Version: type: integer description: x402 protocol version. example: 2 error: type: string description: Why payment is required or was rejected. resource: $ref: '#/components/schemas/PaymentResource' accepts: type: array description: >- Accepted Molpha payment options. Empty on `POST /v1/round/execute`, where only the API source requires payment. items: $ref: '#/components/schemas/PaymentRequirements' extensions: $ref: '#/components/schemas/PaymentExtensions' ApiConfigRequest: type: object description: Off-chain HTTP API configuration. Its canonical hash is the source ID. required: - url - method properties: url: type: string description: Target API URL. Must use `http` or `https`. example: https://api.example.com/v1/price method: type: string description: >- HTTP method. Required: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` or `OPTIONS`. It is hashed into the source ID as sent. example: GET headers: type: object description: >- Request headers. Use `{{secret.name}}` placeholders with `encKeyBundle` for private APIs. additionalProperties: type: string example: {} responseParser: type: string description: JSONPath expression to extract the value from the API response. example: $.data.price valueTransform: type: string description: Optional post-parse transform (e.g. `multiply:1e6`). example: multiply:1e6 aggregation: allOf: - $ref: '#/components/schemas/AggregationRequest' description: >- Selects median tolerance mode. Omit it for exact mode. It is part of the source ID; `"mode":"exact"` is rejected. EncKeyBundleRequest: type: object description: >- End-to-end encryption envelope for private API configs. Omit for plaintext configs. properties: ephemeralPub: type: string description: Ephemeral public key used to encrypt the config (hex). nonceSym: type: string description: Symmetric encryption nonce (12 bytes, hex). ciphertext: type: string description: Encrypted API configuration payload (hex). envelopes: type: object description: >- Per-node encrypted key envelopes. Keys are decimal node indices as strings; values are hex. Send one for every node in the registry; the gateway forwards each selected node only its own. additionalProperties: type: string AttestationData: type: object properties: attestation: type: object properties: payload: type: object properties: value: type: string description: >- Fixed 32-byte packed value (hex). Unsigned in exact mode, signed int256 in tolerance mode. sourceId: type: string description: 32-byte source ID (hex), the canonical API-config hash. registryVersion: type: integer example: 42 signaturesRequired: type: integer example: 3 timestamp: type: integer description: Gateway-assigned round time in unix milliseconds. example: 1700100000000 signature: type: object properties: signature: type: string description: 32-byte aggregate Schnorr scalar (hex). commitment: type: string description: 20-byte commitment address (hex). signersBitmap: type: string description: 32-byte big-endian bitmap of participating signers (hex). value: type: string description: Decimal rendering of `payload.value` (trailing zeros trimmed). example: '42150125000000' fresh: type: boolean example: true configHash: type: string description: >- API-config commitment echoed from the node round (currently equal to `sourceId`). aggregation: allOf: - $ref: '#/components/schemas/AggregationRequest' description: >- Echo of the request's median-tolerance policy; present only in tolerance mode. PaymentResource: type: object properties: url: type: string description: Absolute URL of the request. example: https://gateway.molpha.io/v1/x402/execute description: type: string example: Molpha oracle round mimeType: type: string example: application/json PaymentRequirements: type: object description: One accepted x402 v2 payment option. The payment must match it exactly. properties: scheme: type: string description: Payment scheme. example: exact network: type: string description: Solana CAIP-2 network identifier. example: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 amount: type: string description: >- Round price in USDC atomic units (decimal string): `x402_round_base + (signatures_required + registry.redundancy_buffer) * reward_per_signature`. example: '1030' asset: type: string description: USDC mint address from the on-chain `ProtocolConfig`. payTo: type: string description: >- Protocol treasury owner, the `ProtocolConfig` PDA. Never the gateway. maxTimeoutSeconds: type: integer description: Suggested timeout for completing the payment. example: 60 extra: type: object description: >- Facilitator and request binding fields: `feePayer` (the facilitator's fee payer) and `memo` (hex `MOLPHA_X402_REQUEST_V1` commitment to program, gateway, source, quorum and registry version). additionalProperties: type: string PaymentExtensions: type: object description: Non-Molpha payment terms carried beside `accepts`. properties: upstream: $ref: '#/components/schemas/UpstreamQuote' AggregationRequest: type: object description: >- Median tolerance policy. Nodes fetch independently, exclude observations more than `maxDeviationBps` from the lower median, and sign the lower median of the surviving values as a signed int256. Requires a quorum of at least 3. properties: mode: type: string enum: - tolerance example: tolerance rule: type: string enum: - median example: median maxDeviationBps: type: integer description: Largest allowed deviation from the lower median, in basis points. example: 50 maxAgeMs: type: integer minimum: 1 description: >- Largest allowed age of an observation, in milliseconds. Must be greater than 0. example: 2000 numeric: $ref: '#/components/schemas/AggregationNumeric' UpstreamQuote: type: object description: >- Quote for a paywalled API source. The caller pays the source directly, one authorization per eligible node. properties: provider: type: string description: >- ID of the integrated provider whose x402 host the source is on. Present only for such a source. resource: type: string description: The source URL. signaturesRequired: type: integer redundancyBuffer: type: integer nodeCount: type: integer eligibleSetSize: type: integer description: Number of source authorizations to sign. supportedX402Versions: type: array items: type: integer error: type: string description: >- The source's own response when it was paywalled without being declared. AggregationNumeric: type: object description: How observed decimals become the signed integer. properties: type: type: string enum: - int256 example: int256 decimals: type: integer description: The signed value is scaled by `10^decimals`. example: 8 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.