Execute a subscription round

curl --request POST \
  --url https://gateway.molpha.io/v1/round/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "signaturesRequired": 3,
  "registryVersion": 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({
    signaturesRequired: 3,
    registryVersion: 42,
    apiConfig: {
      url: 'https://api.example.com/v1/price',
      method: 'GET',
      headers: {},
      responseParser: '$.data.price',
      valueTransform: 'multiply:1e6'
    }
  })
};

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

import requests

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

payload = {
    "signaturesRequired": 3,
    "registryVersion": 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/round/execute"

	payload := strings.NewReader("{\n  \"signaturesRequired\": 3,\n  \"registryVersion\": 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"
}

{
  "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"
}

{
  "error": "validation failed"
}

{
  "error": "validation failed"
}

POST

round

execute

Execute a subscription round

curl --request POST \
  --url https://gateway.molpha.io/v1/round/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "signaturesRequired": 3,
  "registryVersion": 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({
    signaturesRequired: 3,
    registryVersion: 42,
    apiConfig: {
      url: 'https://api.example.com/v1/price',
      method: 'GET',
      headers: {},
      responseParser: '$.data.price',
      valueTransform: 'multiply:1e6'
    }
  })
};

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

import requests

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

payload = {
    "signaturesRequired": 3,
    "registryVersion": 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/round/execute"

	payload := strings.NewReader("{\n  \"signaturesRequired\": 3,\n  \"registryVersion\": 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"
}

{
  "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"
}

{
  "error": "validation failed"
}

{
  "error": "validation failed"
}

Body

application/json

Round execution request

Request body for POST /v1/round/execute. With RequestAuth, subscriptionOwner, consumerAuthority, authSig and authTimestamp are also required. With a session token, omit authSig and authTimestamp; the two identity fields are optional.

signaturesRequired

integer

required

Requested quorum: at least protocol min_signers, at most the subscription's max_signers (403 above it) and the current node count.

Example:

3

registryVersion

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

subscriptionOwner

string

Subscription owner pubkey (base58). Equal to consumerAuthority for owner-direct requests. Optional with a session token; if sent it must match the session.

Example:

"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

consumerAuthority

string

Consumer identity that signs RequestAuth (base58): the subscription owner, or a delegate of it. Optional with a session token; if sent it must match the session.

Example:

"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

authSig

string

Ed25519 signature (64 bytes, base58 or 0x hex) by consumerAuthority over keccak256("MOLPHA_REQAUTH_V1" || program_id || gateway_pda || source_id || u8(signaturesRequired) || u64_le(authTimestamp)), where source_id is the canonical apiConfig hash. It only authorizes the request; it is not part of the round. Omit it, and authTimestamp, when sending a session bearer token.

authTimestamp

integer

Unix time in SECONDS at which authSig was signed. Must be within requestAuthWindowSeconds (from GET /v1/info) of the gateway clock, in either direction. Unrelated to the round's millisecond timestamp, which the gateway assigns.

Example:

1700100000

encKeyBundle

object

Optional encryption envelope. Send null or 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. Without sourcePayments the gateway returns the 402 quote instead of running the round.

Response

Signed payload ready for submission or verification

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 a subscription round

Body

Response