Gateway API

The Molpha Gateway turns an API request into a signed DataUpdateResult. It derives the feed identity, checks authorization or payment, dispatches a node round, validates the aggregate signature, and returns a payload that can be submitted to Solana or verified on EVM/Starknet.

Base URL

The SDK default (DEFAULT_GATEWAY_ENDPOINT) is:

https://dev-gateway.molpha.io/

Endpoint overview

Method	Path	Purpose
`GET`	`/health`	Liveness probe
`GET`	`/v1/nodes`	Node metadata and encryption keys
`POST`	`/v1/round/execute`	Subscription-backed signing round
`POST`	`/v1/agent/execute`	x402 agent pay-per-request round
`GET`	`/v1/agent/{payer}/status`	Advisory x402 escrow status

Agent endpoints require agent.enabled: true and a configured gateway keypair (settlement.gateway_keypair_path).

Feed ID derivation

Clients do not send an on-chain create transaction. The gateway and SDK derive the feed identity from the caller, config hash, and quorum:

feed_id = keccak256("MOLPHA_JOB_V1" || owner || api_config_hash || [signatures_required])

Subscription path: owner is consumerAuthority.
Agent path: owner is the payer.
signatures_required is appended as a single byte.

The gateway derives feedId and echoes it in successful responses. The Solana Feed account is created lazily on first successful submit_data_update. Settlement creates a round receipt; it does not write the feed.

Subscription-backed rounds

`POST /v1/round/execute`

Runs a signing round for a subscription owner or active delegate.

{
  "subscriptionOwner": "<base58 pubkey>",
  "consumerAuthority": "<base58 pubkey>",
  "signaturesRequired": 3,
  "timestamp": 1718650000,
  "registryVersion": 1,
  "authSig": "<64-byte ed25519 signature, hex or base58>",
  "apiConfig": {
    "url": "https://api.example.com/price",
    "method": "GET",
    "headers": {},
    "responseParser": "$.data.price",
    "valueTransform": "multiply:1e6"
  },
  "encKeyBundle": null
}

consumerAuthority signs:

hash = sha256("MOLPHA_REQAUTH_V1" || feed_id || uint64_le(timestamp))

timestamp must be within ~300s of the gateway clock. registryVersion must equal the current on-chain registry version. The signature is single-use per (feed_id, timestamp) — retries need a fresh timestamp and signature. An all-zero authSig is rejected.

Status	Typical cause
`400`	Validation failure, stale `registryVersion`, malformed body
`401`	Missing or invalid `authSig`
`403`	Inactive/exhausted subscription, unauthorized delegate, quota committed
`409`	Duplicate round identity
`503`	Node timeout or upstream failure

x402 agent rounds

`POST /v1/agent/execute`

Runs a self-funded pay-per-request round. Agent-specific fields use snake_case; apiConfig matches the subscription execute shape. The payer funds a per-gateway escrow ATA, locks an exact USDC amount equal to the computed round price, signs AgentRequestAuth, and receives the signed result. Settlement via settle_agent_round is asynchronous.

{
  "payer": "<base58 pubkey>",
  "canonical_timestamp": 1718650000,
  "signatures_required": 3,
  "amount": 1030,
  "registry_version": 1,
  "agent_request_auth_sig": "<64-byte ed25519 signature>",
  "apiConfig": {
    "url": "https://api.example.com/price",
    "method": "GET",
    "headers": {},
    "responseParser": "$.data.price",
    "valueTransform": "multiply:1e6"
  },
  "encKeyBundle": null
}

Round price (USDC atomic units):

price = protocol_config.agent_round_base
      + signatures_required × protocol_config.agent_round_per_sig

amount must equal that price exactly. agent_request_auth_sig may be omitted on the unfunded first request of the 402 discovery flow. AgentRequestAuth hash:

body = borsh(agent_escrow_pda, gateway_pda, feed_id, canonical_timestamp_le, amount_le)
hash = sha256("MOLPHA_AGENT_REQAUTH_V1" || body)
sig  = ed25519_sign(payer, hash)

If the escrow ATA is underfunded (available balance = ATA − committed unsettled amounts), the gateway returns a standard x402 envelope:

{
  "x402Version": 1,
  "error": "payment required: escrow ATA underfunded",
  "accepts": [{
    "scheme": "exact",
    "network": "solana-devnet",
    "maxAmountRequired": "1030",
    "payTo": "<escrow ATA>",
    "asset": "<USDC mint>",
    "resource": "/v1/agent/execute",
    "description": "Molpha agent round for feed 0x…",
    "maxTimeoutSeconds": 60,
    "extra": {
      "agent": "<escrow PDA>",
      "gateway": "<gateway PDA>",
      "feedId": "0x…",
      "canonicalTimestamp": 1718650000,
      "amount": "1030",
      "payer": "<payer>",
      "currentAtaBalance": "0",
      "committedAmount": "0",
      "note": "fund at least the shortfall, sign AgentRequestAuth over (agent, gateway, feedId, canonicalTimestamp, amount), then retry with the same canonical_timestamp"
    }
  }]
}

402 flow:

Call execute (signature optional) → receive 402.
Create/fund payTo with at least maxAmountRequired USDC.
Sign AgentRequestAuth over the extra fields.
Retry with the same canonical_timestamp and the signature.

Status	Typical cause
`400`	Validation failure, `amount` ≠ price, stale `registry_version` / timestamp
`401`	Missing or invalid `agent_request_auth_sig` on a funded request
`402`	Escrow ATA underfunded or missing
`403`	Escrow paused or payer/authority mismatch
`409`	Duplicate `canonical_timestamp` for this feed identity
`503`	Node round timeout or upstream failure

`GET /v1/agent/{payer}/status`

Advisory read of escrow state. Optional query signatures_required (default 1) controls the price quote. The escrow is per (payer, gateway) — the gateway derives and returns both addresses.

{
  "payer": "<base58 pubkey>",
  "gateway": "<gateway PDA>",
  "escrow": "<escrow PDA>",
  "exists": true,
  "authority": "<base58 pubkey>",
  "status": "Active",
  "ataAddress": "<ATA>",
  "ataExists": true,
  "ataBalance": "2060",
  "committedAmount": "1030",
  "quotedNextPrice": "1030",
  "unsettledRounds": 1
}

USDC amounts are decimal strings of atomic units. exists: false is normal before the first successful settlement.

Data response

Successful round responses return the same signed payload shape. Live rounds always set fresh: true.

{
  "status": "completed",
  "data": {
    "feedId": "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
  }
}

Serve lifecycle

Validate JSON, pubkeys, timestamps, and API config.
Derive api_config_hash and feed_id.
Verify request auth or x402 funding + AgentRequestAuth.
Read advisory on-chain state.
Reserve the round in the settlement outbox.
Dispatch to nodes.
Validate returned aggregate signature identity.
Complete the outbox record (pending).
Return the signed payload.

Settlement worker drains pending rows into settle_round_receipt or settle_agent_round when settlement.enabled is true.

Round-record PDAs

Replay protection is the unique round-record PDA init:

Path	Seeds
Subscription / delegate	`["molpha_round", consumer_authority, api_config_hash, signatures_required, timestamp_le]`
x402 agent	`["molpha_agent_round", authority, gateway, api_config_hash, signatures_required, canonical_timestamp_le]`

Self-hosting

The gateway is a Go service configured by YAML and environment variables. There is no separate operator “run-gateway” guide — use this section and the gateway repository config.

server:
  port: 8080

solana:
  rpc_url: https://api.devnet.solana.com
  program_id: MoLFGDpFoVnQgwbkTNScKPohCxhbfd61JjFrnotuwzh
  usdc_mint: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

agent:
  enabled: true
  protocol_config_ttl_seconds: 30
  x402_network: solana-devnet
  timestamp_skew_seconds: 300

settlement:
  enabled: true
  db_path: data/settlement-outbox.db
  gateway_keypair_path: /secure/path/gateway.json
  settle_interval_seconds: 10
  settle_batch_limit: 25
  settle_max_attempts: 10

When agent.enabled is true, settlement.gateway_keypair_path is required because AgentRequestAuth binds the gateway PDA. If settlement is disabled, served rounds can remain pending indefinitely. Settlement uses the on-chain protocol_config.usdc_mint; solana.usdc_mint only overrides serve-time ATA derivation and must match on-chain.

Operational notes

Use durable storage for the settlement outbox.
Monitor pending outbox records and round timeout rates.
Keep Solana RPC latency low for escrow and subscription reads.
Verify returned payloads before application use.

Get Started

Quickstarts

AI Agents

Access Models

Core Concepts

Guides

Gateways

Verifiers

Protocol

Reference

Resources

Base URL

Endpoint overview

Feed ID derivation

Subscription-backed rounds

`POST /v1/round/execute`

x402 agent rounds

`POST /v1/agent/execute`

`GET /v1/agent/{payer}/status`

Data response

Serve lifecycle

Round-record PDAs

Self-hosting

Operational notes

​Base URL

​Endpoint overview

​Feed ID derivation

​Subscription-backed rounds

​POST /v1/round/execute

​x402 agent rounds

​POST /v1/agent/execute

​GET /v1/agent/{payer}/status

​Data response

​Serve lifecycle

​Round-record PDAs

​Self-hosting

​Operational notes

Base URL

Endpoint overview

Feed ID derivation

Subscription-backed rounds

`POST /v1/round/execute`

x402 agent rounds

`POST /v1/agent/execute`

`GET /v1/agent/{payer}/status`

Data response

Serve lifecycle

Round-record PDAs

Self-hosting

Operational notes