Skip to main content
A gateway turns an application request into a Molpha signing round. It is the HTTP entry point to the oracle protocol: it discovers the registry, selects nodes, dispatches the API config over libp2p, collects partial Schnorr signatures on GossipSub, aggregates them, and returns a payload ready for verification. Agent endpoints are served only when agent.enabled is true in gateway configuration. For interactive request/response schemas and the API playground, use the HTTP API pages generated from gateway-openapi.yaml.

​
Responsibilities

  • Accept SDK, backend, and agent requests.
  • Authenticate owner-mode requests.
  • Quote and validate exact agent round pricing (amount == price).
  • Return x402 envelopes when pay-per-request escrow is underfunded.
  • Dispatch node rounds and collect aggregate signatures.
  • Maintain a settlement outbox for served rounds.
  • Self-host via YAML/env config (see Self-hosting below).

​
Base URLs

​
Endpoints

The TypeScript SDK gateway client and MCP server wrap these HTTP endpoints for application and AI clients. 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:
  • 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 authentication

For POST /v1/round/execute, consumerAuthority signs:
feed_id is derived from (consumerAuthority, apiConfig, signaturesRequired). timestamp must be within the gateway clock skew window (default 300s). 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.

​
x402 agent authentication

For POST /v1/agent/execute, the payer locks an exact USDC amount equal to the computed round price and signs AgentRequestAuth. Settlement via settle_agent_round is asynchronous. Round price (USDC atomic units):
AgentRequestAuth hash:
agent_request_auth_sig may be omitted on the unfunded first request of the 402 discovery flow. After funding the escrow ATA, retry with the same canonical_timestamp and the signature. See x402 escrow for the full payment loop.

​
Data response

Successful round responses return the same signed payload shape from both execute paths. Live rounds always set fresh: true. Schema: DataUpdateResponse in the OpenAPI spec.

​
Serve lifecycle

  1. Validate JSON, pubkeys, timestamps, and API config.
  2. Derive api_config_hash and feed_id.
  3. Verify request auth or x402 funding + AgentRequestAuth.
  4. Read advisory on-chain state.
  5. Reserve the round in the settlement outbox.
  6. Dispatch to nodes.
  7. Validate returned aggregate signature identity.
  8. Complete the outbox record (pending).
  9. 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:

​
Self-hosting

The gateway is a Go service configured by YAML and environment variables.
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.

​
Why gateways are first-class in Brebeneskul

Brebeneskul adds economic routing around each request. The gateway is no longer only a convenience wrapper around nodes; it is also the coordination point for access models, payment checks, x402 envelopes, and settlement batching.

​
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.

HTTP API

OpenAPI reference with schemas and interactive playground.

x402 escrow

Pay-per-request agent access and settlement.