Gateway API - Molpha Oracle Protocol

The Molpha Gateway is the HTTP front door to the Molpha oracle protocol. You send it a job execution request; it fans the request out to the oracle node set over a libp2p P2P network, waits for the nodes to fetch the data and produce an aggregated Schnorr signature, and returns the signed result to you. A single execute call gives you everything needed to settle a value on-chain: the value, the aggregated signature (s, rx, ryParity), the set of signers, and the on-chain commitment address.

The gateway is stateless with respect to results — every execute call triggers a fresh oracle round. There is no caching layer at the gateway; freshness is guaranteed by a per-request timestamp.

Base URL

https://gateway.molpha.io

All endpoints are unversioned at the host level; resource versioning is in the path (/v1/...).

Quick start

Discover the node set

Call GET /v1/nodes to learn which oracle nodes exist and their signing keys.

Read the job config

Call GET /v1/jobs/{jobId}/config to learn how many signatures the job requires.

Sign and execute

Build an authSig over the job ID and a current timestamp, then call POST /v1/jobs/{jobId}/execute to get the signed result.

The TypeScript SDK does all three steps for you — see Using the SDK.

Authentication

The execute endpoint authenticates the caller against the on-chain job owner. You prove ownership by signing a message with the job owner’s ed25519 key (a standard Solana keypair). The message to sign is:

keccak256( jobId_bytes || uint64_be(timestamp) )

jobId_bytes — the 32 raw bytes of the job ID.
timestamp — the same uint64 Unix-seconds value you put in the request body, big-endian.

The resulting 64-byte ed25519 signature is sent (hex-encoded) as authSig. The gateway recovers the job owner from Solana and rejects the request if the signature does not match.

Because the signed message includes the timestamp, the signature is single-use for a given timestamp. The SDK recomputes authSig on every retry attempt with a fresh timestamp.

import { keccak_256 } from "@noble/hashes/sha3.js";

function authMessage(jobId: string, timestamp: bigint): Uint8Array {
  const jobIdBytes = Buffer.from(jobId.replace(/^0x/, ""), "hex");
  const tsBuf = new Uint8Array(8);
  new DataView(tsBuf.buffer).setBigUint64(0, timestamp, false); // big-endian

  const preimage = new Uint8Array(jobIdBytes.length + 8);
  preimage.set(jobIdBytes, 0);
  preimage.set(tsBuf, jobIdBytes.length);

  return keccak_256(preimage);
}

Endpoints

GET /health

Liveness probe. Returns 200 OK when the service is up. No request parameters.

curl https://gateway.molpha.io/health

Status	Meaning
`200`	Service healthy
`503`	Service degraded

GET /v1/nodes

Returns the configured oracle node set, including each node’s libp2p address and the compressed secp256k1 signing key used for end-to-end encryption.

curl https://gateway.molpha.io/v1/nodes

Response

status

string

Always "ok".

data.nodes

Node[]

Show Node

index

number

Stable index of the node within the registry. Used by the selection algorithm and the encryption envelope map.

peerId

string

libp2p peer ID, derived from the signing key.

address

string

libp2p multiaddr, e.g. /ip4/127.0.0.1/tcp/9000.

signingKey

string

Compressed secp256k1 public key (66-char hex). Used for ECDH key agreement when encrypting an API config for a node.

Response

{
  "status": "ok",
  "data": {
    "nodes": [
      {
        "index": 0,
        "peerId": "12D3KooW...",
        "address": "/ip4/127.0.0.1/tcp/9000",
        "signingKey": "02a1b2c3..."
      }
    ]
  }
}

GET /v1/jobs//config

Fetches the on-chain selection parameters for a job.

jobId

string

required

32-byte job ID, hex-encoded (64 hex chars). A leading 0x is accepted and stripped.

curl https://gateway.molpha.io/v1/jobs/$JOB_ID/config

Response

status

string

Always "ok".

data.signaturesRequired

number

Number of node signatures required to form a valid aggregated signature for this job.

data.redundancyBuffer

number

Extra nodes selected beyond signaturesRequired to tolerate failures. Group size = signaturesRequired + redundancyBuffer.

data.decimals

number

Fixed-point decimals the job’s value is scaled to.

Response

{
  "status": "ok",
  "data": {
    "signaturesRequired": 3,
    "redundancyBuffer": 1,
    "decimals": 8
  }
}

Errors

Status	`error`	Cause
`400`	`invalid job ID`	`jobId` is not 32-byte hex
`404`	`job not found`	No job account exists on-chain
`500`	`failed to fetch redundancy buffer`	Upstream Solana read failed

POST /v1/jobs//execute

Triggers an oracle round and returns the signed, aggregated result. This is the core endpoint.

jobId

string

required

32-byte job ID, hex-encoded (64 hex chars). A leading 0x is accepted and stripped.

Request body

timestamp

number

required

Unix time in seconds. Must satisfy |now - timestamp| ≤ maxAge. Also part of the signed authSig message. With maxAge: 0 only the exact current second is accepted.

registryVersion

number

Node-registry version the round should run against. Folded into the deterministic round ID.

maxAge

number

Allowed clock skew, in seconds, between timestamp and the gateway’s clock.

authSig

string

required

ed25519 signature (64 bytes, hex; 0x accepted) over keccak256(jobId_bytes || uint64_be(timestamp)). Verified against the on-chain job owner. See Authentication.

apiConfig

object

required

Describes the data source the nodes should fetch.

Show apiConfig

url

string

required

Source URL. Must be a valid URL with an http or https scheme.

method

string

HTTP method: one of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS (case-insensitive). Defaults to GET in the SDK.

headers

object

Request headers as a string→string map. Header names must be non-empty.

responseParser

string

Expression used to extract the value from the response (e.g. a JSON path).

valueTransform

string

Transform applied to the parsed value before signing (e.g. multiply:1e6).

encKeyBundle

object | null

Optional end-to-end encryption envelope. Omit or send null for plaintext API configs. When present, the gateway forwards each node only its own envelope entry. See End-to-end encryption.

Show encKeyBundle

ephemeralPub

string

Ephemeral public key, hex (0x accepted).

nonceSym

string

Symmetric nonce, exactly 12 bytes, hex.

ciphertext

string

Encrypted API config, hex.

envelopes

object

Map of nodeIndex (decimal string) → wrapped symmetric key, hex. Keys must parse as uint32; values must be non-empty hex.

curl -X POST https://gateway.molpha.io/v1/jobs/$JOB_ID/execute \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": 1718650000,
    "registryVersion": 1,
    "maxAge": 60,
    "authSig": "0x<128-hex-char-signature>",
    "apiConfig": {
      "url": "https://api.example.com/price",
      "method": "GET",
      "headers": {},
      "responseParser": "$.data.price",
      "valueTransform": "multiply:1e6"
    },
    "encKeyBundle": null
  }'

Response

status

string

Always "completed" on success.

data

object

Show data

jobId

string

The job ID, hex.

value

string

Human-readable aggregated value.

valuePacked

string

Packed/encoded value used for on-chain settlement.

timestamp

number

Round timestamp (echoes the request).

registryVersion

number

Registry version the round ran against.

signaturesRequired

number

Number of signatures required for this job.

configHash

string

Hash of the API config used by the nodes.

signersBitmap

string

Bitmap of node indices that contributed to the aggregated signature.

string

Schnorr signature scalar s.

string

Schnorr nonce point x-coordinate Rx.

ryParity

number

Parity bit of the nonce point y-coordinate.

commitmentAddr

string

On-chain commitment address for this round.

fresh

boolean

Always true — the result was produced by this round.

Response

{
  "status": "completed",
  "data": {
    "jobId": "1a2b3c...",
    "value": "65432.10",
    "valuePacked": "0x...",
    "timestamp": 1718650000,
    "registryVersion": 1,
    "signaturesRequired": 3,
    "configHash": "0x...",
    "signersBitmap": "0x07",
    "s": "0x...",
    "rx": "0x...",
    "ryParity": 0,
    "commitmentAddr": "0x...",
    "fresh": true
  }
}

Errors

All errors use the envelope { "error": "<message>" }.

Status	`error` (examples)	Cause
`400`	`jobId is required`	Empty path parameter
`400`	`malformed request body`	Body is not valid JSON
`400`	`timestamp: is required`	`timestamp` missing or zero
`400`	`timestamp: must be within the allowed time range`	Clock skew exceeds `maxAge`
`400`	`jobId: must be 32-byte hex`	Bad job ID format
`400`	`authSig: must be 64 bytes, got N`	Signature wrong length
`400`	`authSig: signature does not match job owner`	Signature does not verify against the on-chain owner
`400`	`apiConfig.url: scheme must be http or https`	Invalid source URL
`400`	`apiConfig.method: must be a valid HTTP method`	Unsupported method
`503`	`upstream timeout`	No aggregated signature within `node.agg_wait_seconds`
`503`	(node-supplied message)	A node reported an error for the round
`500`	`internal server error`	Unexpected dispatch/build failure

A 503 typically means too few nodes responded in time. Retry with a fresh timestamp — this also re-rolls the deterministic node selection, which often resolves transient failures. The SDK does this automatically (maxRetries, default 15).

End-to-end encryption

When an API config contains secrets (API keys, tokens), you can encrypt it so that only the nodes selected for the round can read it — the gateway never sees the plaintext. The flow:

Locally compute which nodes will be selected for (jobId, registryVersion, timestamp) using the deterministic selection algorithm.
Resolve secret placeholders (e.g. {{secret.appid}}) in the API config.
Encrypt the resolved config with a fresh symmetric key, then wrap that symmetric key for each selected node via ECDH against its signingKey.
Send the result as encKeyBundle, keyed by each node’s index.

The SDK’s encrypt option handles all of this. The envelopes map must contain exactly the selected node indices, since selection is timestamp-dependent.

Node selection depends on timestamp. If you retry with a new timestamp, you must recompute the selection and re-encrypt for the new node set. The SDK does this on each attempt.

Using the SDK

The TypeScript SDK wraps node discovery, job config, deterministic selection, encryption, auth signing, and retries.

import { MolphaGateway, createSignerFromKeypairFile } from "@molpha/gateway-sdk";

const gw = new MolphaGateway("https://gateway.molpha.io");

// Sign as the job owner using a Solana keypair JSON file
const signer = createSignerFromKeypairFile("~/.config/solana/id.json");

const result = await gw.execute({
  jobId: "1a2b3c...",          // 64-char hex, no 0x
  registryVersion: 1,
  apiConfig: {
    url: "https://api.example.com/price",
    method: "GET",
    responseParser: "$.data.price",
    valueTransform: "multiply:1e6",
  },
  signer,
  maxAge: 60,
  maxRetries: 15,
});

console.log(result.value, result.s, result.rx, result.commitmentAddr);

The SDK retries with a fresh timestamp on each failed attempt, recomputing both authSig and the node selection.

Protocol internals (reference)

You don’t need these to use the API, but they explain how a round works under the hood.

Transport. The gateway sends each selected node a binary RoundRequest over a libp2p stream on protocol /molpha/1.0.0.
Aggregation. Nodes publish the aggregated signature as JSON on the GossipSub topic molpha/agg-sig/v1. The gateway matches the message by the deterministic round ID.
Deterministic round ID. Computed as keccak256( keccak256("MOLPHA_PULL_ROUND_V1") || jobId || uint32_be(registryVersion) || uint64_be(timestamp) ), so the same inputs always identify the same round.
Round ID ≠ randomness. Because the round ID is deterministic in timestamp, freshness and selection both rotate purely by changing the timestamp.

​Base URL

​Quick start

​Authentication

​Endpoints

​GET /health

​GET /v1/nodes

​GET /v1/jobs//config

​POST /v1/jobs//execute

​Request body

​Response

​Errors

​End-to-end encryption

​Using the SDK

​Protocol internals (reference)

Base URL

Quick start

Authentication

Endpoints

GET /health

GET /v1/nodes

GET /v1/jobs//config

POST /v1/jobs//execute

Request body

Response

Errors

End-to-end encryption

Using the SDK

Protocol internals (reference)