Gateway client

sdk.gateway is a MolphaGateway: it signs the request, runs a round on a Molpha gateway and returns an Attestation. This page covers its methods and retry behaviour; for the HTTP API, auth digest and error codes, see gateways.

The gateway response is unverified. The SDK checks that the response matches what you asked for (sourceId, signaturesRequired, aggregation) but does not check the aggregate signature. Verify the attestation before you act on its value: submit it to Solana, or call the EVM, Starknet or Solana verifier.

Endpoints

The client posts to its endpoints in order and moves to the next one on any retryable failure (see retries and errors). The default is DEFAULT_GATEWAY_ENDPOINT, https://gateway.molpha.io/ (devnet).

const sdk = new MolphaSDK({
  connection,
  wallet,
  endpoints: [DEFAULT_GATEWAY_ENDPOINT, { url: "https://gateway-2.example", gatewayAuthority: "<base58>" }],
});

The request signature binds the gateway’s on-chain account, so the client needs each gateway’s authority key. When you omit gatewayAuthority, the client reads it once per endpoint from GET /v1/info and throws if the gateway reports a different programId.

`requestSignedData`

const result = await sdk.gateway.requestSignedData({
  apiConfig: { url: "https://api.example.com/price", responseParser: "$.price" },
  signaturesRequired: 3,
});

For each call the SDK:

Canonicalizes apiConfig and derives its sourceId (see feeds). An invalid aggregation, or tolerance mode with signaturesRequired < 3, throws AggregationConfigError before any request.
Reads the current registry version, redundancy buffer and node count from Solana, unless you pass a context.
Signs RequestAuth with a fresh authTimestamp for each attempt and endpoint, and posts to POST /v1/round/execute.
Rejects a response whose sourceId, signaturesRequired or aggregation differs from the request, or that lacks a signed field.

The gateway assigns the round’s timestamp (unix milliseconds); you never send one. How rounds are timed and shared between callers is described in round timing. All options are listed in RequestSignedDataOptions. The ones you set most often:

Option	Default	Meaning
`subscriptionOwner`	wallet public key	Subscription that pays for the round.
`consumerAuthority`	`subscriptionOwner`	The caller: the owner or one of its delegates.
`maxAge`	`60`	Maximum accepted value age, in seconds, sent to the gateway.
`maxRetries`	`6`	Maximum attempts. See retries and errors.
`timeoutMs`	`35000`	Per-request timeout. Keep it above the gateway’s round wait, or a retry starts a second round.
`context`	none	Cached registry inputs from `prepareContext`.

Private APIs

Put secrets in the URL or headers as {{secret.<name>}} placeholders and pass their values in encrypt.secrets:

const result = await sdk.gateway.requestSignedData({
  apiConfig: {
    url: "https://api.example.com/private-price?key={{secret.apiKey}}",
    responseParser: "$.price",
  },
  signaturesRequired: 3,
  encrypt: { secrets: { apiKey: process.env.API_KEY! } },
});

The SDK encrypts the secrets for every node of the registry version, because the committee is not known until the gateway stamps the round. Before encrypting, MolphaSDK checks the gateway’s node keys against the on-chain Node accounts (solana.verifyNodeKeysForPrivateApi). A standalone MolphaGateway throws unless you pass verifyNodeKeys or set the unsafe allowUnverifiedNodeKeysForPrivateApi. The sourceId is derived from the config with its placeholders, never from the secret values.

Paywalled API sources

When the API source itself answers HTTP 402 (x402), pass sourcePayment to pay it from your own EVM wallet:

import { createEvmSignerFromPrivateKey } from "@molpha/sdk";

const result = await sdk.gateway.requestSignedData({
  apiConfig,
  signaturesRequired: 3,
  sourcePayment: { signer: createEvmSignerFromPrivateKey(process.env.SOURCE_PAYER_KEY!) },
});

The SDK reads the source’s 402 terms and signs one authorization per node in the round’s eligible set, min(signaturesRequired + redundancyBuffer, nodeCount). Only authorizations a node spends settle. Payment goes to the source, not to Molpha, and the round still costs one unit of subscription quota. The SDK signs exact USDC payments on Base and Base Sepolia only. Without sourcePayment, a paywalled source throws UpstreamPaymentRequiredError with the gateway’s quote. This is separate from paying Molpha per request with x402. The SDK does not wrap the x402 pay-per-request endpoint; call it over HTTP as described there.

`prepareContext`

const context = await sdk.gateway.prepareContext();

for (const apiConfig of configs) {
  await sdk.gateway.requestSignedData({ apiConfig, signaturesRequired: 3, context });
}

Reads the registry version, redundancy buffer and node count from Solana and the node list from GET /v1/nodes, in parallel, and returns a RoundContext. With a full context, each requestSignedData is a single POST. Nothing is cached automatically. If the gateway reports that the context’s registry version is no longer current, the call re-reads the registry once and retries without spending an attempt; still refresh a long-lived context when the registry version changes.

`requestAndSubmit`

const { result, signature, feed } = await sdk.requestAndSubmit({ apiConfig, signaturesRequired: 3 });

Calls requestSignedData with the same options, then sdk.solana.submitAttestation(result), which verifies the signature on-chain and writes the submitter’s Feed account. If the round succeeds but the submit fails, it throws SubmitFailedError. The round is already paid for, so resubmit error.result instead of requesting a new one:

import { SubmitFailedError } from "@molpha/sdk";

try {
  await sdk.requestAndSubmit({ apiConfig, signaturesRequired: 3 });
} catch (err) {
  if (!(err instanceof SubmitFailedError)) throw err;
  await sdk.solana.submitAttestation(err.result);
}

To update many feeds, use requestMany.

Retries and errors

requestSignedData makes up to maxRetries attempts and throws the last error when they run out. Each attempt tries every endpoint in order. There is no idempotency key: every attempt the gateway accepts is a new round that spends another unit of quota.

Gateway answer	SDK behaviour
HTTP 409	You already have a round for this source and quorum in the current tick. Tries the next endpoint, then retries after one tick (`ROUND_TICK_MS`, 100 ms) plus up to 20 ms of jitter.
HTTP 503 or 429	Gateway at capacity, too few nodes accepted, or rate limited. Tries the next endpoint, then waits the later of `Retry-After` and the backoff step (250 ms doubling to 5 s), plus jitter.
HTTP 400, registry version not current	Re-reads the registry once and retries immediately, without spending an attempt.
HTTP 400, 401 or 403	Throws `GatewayError` with `status` at once. 403 means the subscription is inactive or its round quota is spent.
HTTP 402	Paywalled source. Signs source payments and retries if `sourcePayment` is set; otherwise throws `UpstreamPaymentRequiredError`.
Timeout, network error, other 5xx	Tries the next endpoint, then waits the backoff step (half randomized).

retryDelayMs(cause, failures) exposes the delay calculation. Error classes are listed in errors.

​Endpoints

​requestSignedData

​Private APIs

​Paywalled API sources

​prepareContext

​requestAndSubmit

​Retries and errors

Endpoints

`requestSignedData`

Private APIs

Paywalled API sources

`prepareContext`

`requestAndSubmit`

Retries and errors