Execute an x402 pay-per-request round

curl --request POST \
  --url https://gateway.molpha.io/v1/x402/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "signatures_required": 3,
  "registry_version": 42,
  "apiConfig": {
    "url": "https://api.example.com/v1/price",
    "method": "GET",
    "headers": {},
    "responseParser": "$.data.price",
    "valueTransform": "multiply:1e6"
  }
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    signatures_required: 3,
    registry_version: 42,
    apiConfig: {
      url: 'https://api.example.com/v1/price',
      method: 'GET',
      headers: {},
      responseParser: '$.data.price',
      valueTransform: 'multiply:1e6'
    }
  })
};

fetch('https://gateway.molpha.io/v1/x402/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://gateway.molpha.io/v1/x402/execute"

payload = {
    "signatures_required": 3,
    "registry_version": 42,
    "apiConfig": {
        "url": "https://api.example.com/v1/price",
        "method": "GET",
        "headers": {},
        "responseParser": "$.data.price",
        "valueTransform": "multiply:1e6"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.molpha.io/v1/x402/execute"

	payload := strings.NewReader("{\n  \"signatures_required\": 3,\n  \"registry_version\": 42,\n  \"apiConfig\": {\n    \"url\": \"https://api.example.com/v1/price\",\n    \"method\": \"GET\",\n    \"headers\": {},\n    \"responseParser\": \"$.data.price\",\n    \"valueTransform\": \"multiply:1e6\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "status": "completed",
  "data": {
    "attestation": {
      "payload": {
        "value": "<string>",
        "sourceId": "<string>",
        "registryVersion": 42,
        "signaturesRequired": 3,
        "timestamp": 1700100000000
      },
      "signature": {
        "signature": "<string>",
        "commitment": "<string>",
        "signersBitmap": "<string>"
      }
    },
    "value": "42150125000000",
    "fresh": true,
    "configHash": "<string>",
    "aggregation": {
      "mode": "tolerance",
      "rule": "median",
      "maxDeviationBps": 50,
      "maxAgeMs": 2000,
      "numeric": {
        "type": "int256",
        "decimals": 8
      }
    }
  }
}

{
  "error": "validation failed"
}

{
  "x402Version": 2,
  "error": "<string>",
  "resource": {
    "url": "https://gateway.molpha.io/v1/x402/execute",
    "description": "Molpha oracle round",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "1030",
      "asset": "<string>",
      "payTo": "<string>",
      "maxTimeoutSeconds": 60,
      "extra": {}
    }
  ],
  "extensions": {
    "upstream": {
      "provider": "<string>",
      "resource": "<string>",
      "signaturesRequired": 123,
      "redundancyBuffer": 123,
      "nodeCount": 123,
      "eligibleSetSize": 123,
      "supportedX402Versions": [
        123
      ],
      "error": "<string>"
    }
  }
}

{
  "error": "validation failed"
}

{
  "error": "validation failed"
}

{
  "error": "validation failed"
}

POST

x402

execute

Execute an x402 pay-per-request round

curl --request POST \
  --url https://gateway.molpha.io/v1/x402/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "signatures_required": 3,
  "registry_version": 42,
  "apiConfig": {
    "url": "https://api.example.com/v1/price",
    "method": "GET",
    "headers": {},
    "responseParser": "$.data.price",
    "valueTransform": "multiply:1e6"
  }
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    signatures_required: 3,
    registry_version: 42,
    apiConfig: {
      url: 'https://api.example.com/v1/price',
      method: 'GET',
      headers: {},
      responseParser: '$.data.price',
      valueTransform: 'multiply:1e6'
    }
  })
};

fetch('https://gateway.molpha.io/v1/x402/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://gateway.molpha.io/v1/x402/execute"

payload = {
    "signatures_required": 3,
    "registry_version": 42,
    "apiConfig": {
        "url": "https://api.example.com/v1/price",
        "method": "GET",
        "headers": {},
        "responseParser": "$.data.price",
        "valueTransform": "multiply:1e6"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.molpha.io/v1/x402/execute"

	payload := strings.NewReader("{\n  \"signatures_required\": 3,\n  \"registry_version\": 42,\n  \"apiConfig\": {\n    \"url\": \"https://api.example.com/v1/price\",\n    \"method\": \"GET\",\n    \"headers\": {},\n    \"responseParser\": \"$.data.price\",\n    \"valueTransform\": \"multiply:1e6\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "status": "completed",
  "data": {
    "attestation": {
      "payload": {
        "value": "<string>",
        "sourceId": "<string>",
        "registryVersion": 42,
        "signaturesRequired": 3,
        "timestamp": 1700100000000
      },
      "signature": {
        "signature": "<string>",
        "commitment": "<string>",
        "signersBitmap": "<string>"
      }
    },
    "value": "42150125000000",
    "fresh": true,
    "configHash": "<string>",
    "aggregation": {
      "mode": "tolerance",
      "rule": "median",
      "maxDeviationBps": 50,
      "maxAgeMs": 2000,
      "numeric": {
        "type": "int256",
        "decimals": 8
      }
    }
  }
}

{
  "error": "validation failed"
}

{
  "x402Version": 2,
  "error": "<string>",
  "resource": {
    "url": "https://gateway.molpha.io/v1/x402/execute",
    "description": "Molpha oracle round",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "1030",
      "asset": "<string>",
      "payTo": "<string>",
      "maxTimeoutSeconds": 60,
      "extra": {}
    }
  ],
  "extensions": {
    "upstream": {
      "provider": "<string>",
      "resource": "<string>",
      "signaturesRequired": 123,
      "redundancyBuffer": 123,
      "nodeCount": 123,
      "eligibleSetSize": 123,
      "supportedX402Versions": [
        123
      ],
      "error": "<string>"
    }
  }
}

{
  "error": "validation failed"
}

{
  "error": "validation failed"
}

{
  "error": "validation failed"
}

Headers

PAYMENT-SIGNATURE

string

Base64 x402 v2 payment payload. Omit on the first request to receive the 402 requirements.

Body

application/json

x402 execute request

Request body for POST /v1/x402/execute. It carries no timestamp and no payer, amount, signature or payment reference; payment is in PAYMENT-SIGNATURE.

signatures_required

integer

required

Requested quorum for this round. Must be at least protocol min_signers and at most the current node count.

Example:

3

registry_version

integer

required

Active on-chain registry version. Must match the current version.

Example:

42

apiConfig

object

required

Off-chain HTTP API configuration. Its canonical hash is the source ID.

Hide child attributes

apiConfig.url

string

required

Target API URL. Must use http or https.

Example:

"https://api.example.com/v1/price"

apiConfig.method

string

required

HTTP method. Required: GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS. It is hashed into the source ID as sent.

Example:

"GET"

apiConfig.headers

object

Request headers. Use {{secret.name}} placeholders with encKeyBundle for private APIs.

Hide child attributes

apiConfig.headers.{key}

string

Example:

{}

apiConfig.responseParser

string

JSONPath expression to extract the value from the API response.

Example:

"$.data.price"

apiConfig.valueTransform

string

Optional post-parse transform (e.g. multiply:1e6).

Example:

"multiply:1e6"

apiConfig.aggregation

object

Selects median tolerance mode. Omit it for exact mode. It is part of the source ID; "mode":"exact" is rejected.

Hide child attributes

apiConfig.aggregation.mode

enum<string>

Available options:

tolerance

Example:

"tolerance"

apiConfig.aggregation.rule

enum<string>

Available options:

median

Example:

"median"

apiConfig.aggregation.maxDeviationBps

integer

Largest allowed deviation from the lower median, in basis points.

Example:

50

apiConfig.aggregation.maxAgeMs

integer

Largest allowed age of an observation, in milliseconds. Must be greater than 0.

Required range: x >= 1

Example:

2000

apiConfig.aggregation.numeric

object

How observed decimals become the signed integer.

Hide child attributes

apiConfig.aggregation.numeric.type

enum<string>

Available options:

int256

Example:

"int256"

apiConfig.aggregation.numeric.decimals

integer

The signed value is scaled by 10^decimals.

Example:

8

encKeyBundle

object

End-to-end encryption envelope for private API configs. Omit for plaintext configs.

Hide child attributes

encKeyBundle.ephemeralPub

string

Ephemeral public key used to encrypt the config (hex).

encKeyBundle.nonceSym

string

Symmetric encryption nonce (12 bytes, hex).

encKeyBundle.ciphertext

string

Encrypted API configuration payload (hex).

encKeyBundle.envelopes

object

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.

Hide child attributes

encKeyBundle.envelopes.{key}

string

sourcePayments

string[]

Base64 x402 payloads for a paywalled API source, one per node in the round's eligible set. They pay the source, never Molpha.

x402Source

boolean

Declare a paywalled API source to be quoted in extensions.upstream before running the round.

Response

Signed aggregate; the payment is confirmed

Successful round response, shared by POST /v1/round/execute and POST /v1/x402/execute. The attestation payload and Schnorr signature are what verifiers consume.

status

string

Example:

"completed"

data

object

Hide child attributes

data.attestation

object

Hide child attributes

data.attestation.payload

object

Hide child attributes

data.attestation.payload.value

string

Fixed 32-byte packed value (hex). Unsigned in exact mode, signed int256 in tolerance mode.

data.attestation.payload.sourceId

string

32-byte source ID (hex), the canonical API-config hash.

data.attestation.payload.registryVersion

integer

Example:

42

data.attestation.payload.signaturesRequired

integer

Example:

3

data.attestation.payload.timestamp

integer

Gateway-assigned round time in unix milliseconds.

Example:

1700100000000

data.attestation.signature

object

Hide child attributes

data.attestation.signature.signature

string

32-byte aggregate Schnorr scalar (hex).

data.attestation.signature.commitment

string

20-byte commitment address (hex).

data.attestation.signature.signersBitmap

string

32-byte big-endian bitmap of participating signers (hex).

data.value

string

Decimal rendering of payload.value (trailing zeros trimmed).

Example:

"42150125000000"

data.fresh

boolean

Example:

true

data.configHash

string

API-config commitment echoed from the node round (currently equal to sourceId).

data.aggregation

object

Echo of the request's median-tolerance policy; present only in tolerance mode.

Hide child attributes

data.aggregation.mode

enum<string>

Available options:

tolerance

Example:

"tolerance"

data.aggregation.rule

enum<string>

Available options:

median

Example:

"median"

data.aggregation.maxDeviationBps

integer

Largest allowed deviation from the lower median, in basis points.

Example:

50

data.aggregation.maxAgeMs

integer

Largest allowed age of an observation, in milliseconds. Must be greater than 0.

Required range: x >= 1

Example:

2000

data.aggregation.numeric

object

How observed decimals become the signed integer.

Hide child attributes

data.aggregation.numeric.type

enum<string>

Available options:

int256

Example:

"int256"

data.aggregation.numeric.decimals

integer

The signed value is scaled by 10^decimals.

Example:

8

Gateway API

Rounds

Sign-in sessions

Network

Execute an x402 pay-per-request round

Headers

Body

Response