Class Gateway

Gateway interface for oracle communication

The Gateway class provides the connection between your application and Switchboard oracle operators. It handles:

  • Fetching signed price data from oracles
  • Managing oracle selection and consensus
  • Batch operations for multiple feeds
  • Network latency optimization
  • Variable overrides for dynamic task customization

Gateways are geo-distributed endpoints that route requests to available oracle operators for optimal performance.

Variable Overrides

Variable overrides allow you to dynamically customize oracle task execution by providing key-value pairs that replace variables within oracle jobs. This is particularly useful for:

  • API Key Management: Override API keys for different environments
  • Dynamic Parameters: Change URLs, endpoints, or query parameters
  • A/B Testing: Switch between different data sources
  • Environment Configuration: Use different settings for dev/staging/prod

Usage Examples

// Create gateway
const gateway = new Gateway(program, 'https://gateway.switchboard.xyz');

// Basic feed fetch with API key override
const response = await gateway.fetchSignatures({
  jobs: [buildApiJob('${API_KEY}')], // Job uses ${API_KEY} variable
  numSignatures: 3,
  variableOverrides: {
    'API_KEY': 'prod-api-key-123',
    'BASE_URL': 'https://api.prod.example.com'
  }
});

// Batch processing with environment-specific overrides
const batchResponse = await gateway.fetchSignaturesBatch({
  feedConfigs: [{
    jobs: [buildJob('${ENDPOINT}/price/${SYMBOL}')],
    maxVariance: 0.5,
    minResponses: 2
  }],
  numSignatures: 5,
  variableOverrides: {
    'ENDPOINT': 'https://api.staging.example.com',
    'SYMBOL': 'BTCUSD',
    'TIMEOUT': '30000'
  }
});

// Multi-feed with shared overrides
const multiResponse = await gateway.fetchSignaturesMulti({
  feedConfigs: [
    { jobs: [priceJob1], maxVariance: 1.0, minResponses: 1 },
    { jobs: [priceJob2], maxVariance: 1.5, minResponses: 2 }
  ],
  numSignatures: 4,
  variableOverrides: {
    'API_VERSION': 'v2',
    'RATE_LIMIT': '100'
  }
});

// Consensus with authentication override
const consensusResponse = await gateway.fetchSignaturesConsensus({
  feedConfigs: [{ feed: myFeedConfig }],
  numSignatures: 7,
  variableOverrides: {
    'AUTH_TOKEN': await getAuthToken(),
    'REGION': 'us-east-1'
  }
});

Variable Syntax in Jobs

Variables in oracle jobs use the ${VARIABLE_NAME} syntax:

const httpJob = {
  tasks: [{
    httpTask: {
      url: '${BASE_URL}/api/${VERSION}/price?symbol=${SYMBOL}&key=${API_KEY}',
      method: 'GET',
      headers: {
        'Authorization': 'Bearer ${AUTH_TOKEN}',
        'User-Agent': '${USER_AGENT}'
      }
    }
  }]
};

Best Practices

  1. Security: Never hardcode sensitive API keys in jobs - use overrides
  2. Environment Management: Use overrides to switch between dev/staging/prod
  3. Flexibility: Design jobs with variables for maximum reusability
  4. Validation: Ensure all required variables are provided in overrides
  5. Documentation: Document expected variables in your job definitions

Gateway

Constructors

constructor

Properties

gatewayUrl oracleKey? program

Methods

[toPrimitive] endpoint fetchAttestation fetchBridgingMessage fetchQuote fetchRandomnessReveal fetchSignatures fetchSignaturesBatch fetchSignaturesConsensus fetchSignaturesFromEncoded fetchSignaturesFromEncodedBatch fetchSignaturesFromEncodedMulti fetchSignaturesMulti fetchUpdateBundle initSurge ping test toString

Constructors

constructor

  • new Gateway(
        program: Program,
        gatewayUrl: string,
        oracleKey?: PublicKey,
    ): Gateway

    Constructs a Gateway instance

    Parameters

    • program: Program

      The Anchor program instance

    • gatewayUrl: string

      The URL of the switchboard gateway

    • OptionaloracleKey: PublicKey

      Optional specific oracle key

    Returns Gateway

Properties

ReadonlygatewayUrl

gatewayUrl: string

The URL of the switchboard gateway

Optional ReadonlyoracleKey

oracleKey?: PublicKey

Optional specific oracle key

Readonlyprogram

program: Program

The Anchor program instance

Methods

[toPrimitive]

endpoint

fetchAttestation

  • fetchAttestation(
        params: {
            oracle_ed25519_enclave_signer: string;
            oracle_pubkey: string;
            oracle_reward_wallet: string;
            oracle_secp256k1_enclave_signer: string;
            quote: string;
            recentHash: string;
            timestamp: number;
        },
    ): Promise<AttestEnclaveResponse>

    Fetches signatures from the gateway. REST API endpoint: /api/v1/gateway_attest_enclave

    Parameters

    • params: {
          oracle_ed25519_enclave_signer: string;
          oracle_pubkey: string;
          oracle_reward_wallet: string;
          oracle_secp256k1_enclave_signer: string;
          quote: string;
          recentHash: string;
          timestamp: number;
      }

    Returns Promise<AttestEnclaveResponse>

    A promise that resolves to the attestation response.

    Throws

    if the request fails.

fetchBridgingMessage

fetchQuote

  • fetchQuote(
        params: {
            blockhash: string;
            get_for_guardian: boolean;
            get_for_oracle: boolean;
        },
    ): Promise<FetchQuoteResponse[]>

    Fetches a quote from the gateway.

    REST API endpoint: /api/v1/gateway_fetch_quote

    Parameters

    • params: { blockhash: string; get_for_guardian: boolean; get_for_oracle: boolean }

    Returns Promise<FetchQuoteResponse[]>

    A promise that resolves to the quote response.

    Throws

    if the request fails.

fetchRandomnessReveal

  • fetchRandomnessReveal(
        params:
            | {
                randomnessAccount: PublicKey;
                rpc?: string;
                slot: number;
                slothash: string;
            }
            | { minStalenessSeconds: number; randomnessId: string; timestamp: number },
    ): Promise<RandomnessRevealResponse>

    Fetches the randomness reveal from the gateway.

    Parameters

    • params:
          | {
              randomnessAccount: PublicKey;
              rpc?: string;
              slot: number;
              slothash: string;
          }
          | { minStalenessSeconds: number; randomnessId: string; timestamp: number }

      The parameters for the randomness reveal.

    Returns Promise<RandomnessRevealResponse>

    The randomness reveal response.

fetchSignatures

  • fetchSignatures(
        params: {
            jobs: IOracleJob[];
            maxVariance?: number;
            minResponses?: number;
            numSignatures?: number;
            recentHash?: string;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<{ failures: string[]; responses: FeedEvalResponse[] }>

    Fetches signatures from the gateway.

    REST API endpoint: /api/v1/fetch_signatures

    Parameters

    • params: {
          jobs: IOracleJob[];
          maxVariance?: number;
          minResponses?: number;
          numSignatures?: number;
          recentHash?: string;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<{ failures: string[]; responses: FeedEvalResponse[] }>

    A promise that resolves to the feed evaluation responses.

    Throws

    if the request fails.

fetchSignaturesBatch

  • fetchSignaturesBatch(
        params: {
            feedConfigs: FeedRequestV1[];
            numSignatures?: number;
            recentHash?: string;
            useEd25519?: boolean;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<FetchSignaturesBatchResponse>

    Fetches signatures from the gateway without pre-encoded jobs REST API endpoint: /api/v1/fetch_signatures_batch

    Parameters

    • params: {
          feedConfigs: FeedRequestV1[];
          numSignatures?: number;
          recentHash?: string;
          useEd25519?: boolean;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<FetchSignaturesBatchResponse>

    A promise that resolves to the feed evaluation responses.

    Throws

    if the request fails.

fetchSignaturesConsensus

  • fetchSignaturesConsensus(
        params: {
            feedConfigs: FeedRequest[];
            numSignatures?: number;
            useEd25519?: boolean;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<FetchSignaturesConsensusResponse>

    Fetches signatures using consensus mechanism REST API endpoint: /api/v1/fetch_signatures_consensus

    Parameters

    • params: {
          feedConfigs: FeedRequest[];
          numSignatures?: number;
          useEd25519?: boolean;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<FetchSignaturesConsensusResponse>

    A promise that resolves to the consensus response.

    Throws

    if the request fails.

fetchSignaturesFromEncoded

  • fetchSignaturesFromEncoded(
        params: {
            encodedJobs: string[];
            maxVariance: number;
            minResponses: number;
            numSignatures: number;
            recentHash?: string;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<{ failures: string[]; responses: FeedEvalResponse[] }>

    Fetches signatures from the gateway.

    REST API endpoint: /api/v1/fetch_signatures

    Parameters

    • params: {
          encodedJobs: string[];
          maxVariance: number;
          minResponses: number;
          numSignatures: number;
          recentHash?: string;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<{ failures: string[]; responses: FeedEvalResponse[] }>

    A promise that resolves to the feed evaluation responses.

    Throws

    if the request fails.

fetchSignaturesFromEncodedBatch

  • fetchSignaturesFromEncodedBatch(
        params: {
            encodedConfigs: {
                encodedJobs: string[];
                maxVariance: number;
                minResponses: number;
            }[];
            numSignatures: number;
            recentHash?: string;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<FetchSignaturesBatchResponse>

    Fetches signatures from the gateway. REST API endpoint: /api/v1/fetch_signatures_batch

    Parameters

    • params: {
          encodedConfigs: {
              encodedJobs: string[];
              maxVariance: number;
              minResponses: number;
          }[];
          numSignatures: number;
          recentHash?: string;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<FetchSignaturesBatchResponse>

    A promise that resolves to the feed evaluation responses.

    Throws

    if the request fails.

fetchSignaturesFromEncodedMulti

  • fetchSignaturesFromEncodedMulti(
        params: {
            encodedConfigs: {
                encodedJobs: string[];
                maxVariance: number;
                minResponses: number;
            }[];
            numSignatures: number;
            recentHash?: string;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<FetchSignaturesMultiResponse>

    Parameters

    • params: {
          encodedConfigs: {
              encodedJobs: string[];
              maxVariance: number;
              minResponses: number;
          }[];
          numSignatures: number;
          recentHash?: string;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<FetchSignaturesMultiResponse>

fetchSignaturesMulti

  • fetchSignaturesMulti(
        params: {
            feedConfigs: FeedRequestV1[];
            numSignatures?: number;
            recentHash?: string;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<FetchSignaturesMultiResponse>

    Fetches signatures from multiple feeds

    Parameters

    • params: {
          feedConfigs: FeedRequestV1[];
          numSignatures?: number;
          recentHash?: string;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<FetchSignaturesMultiResponse>

    A promise that resolves to the feed evaluation responses.

    Throws

    if the request fails.

fetchUpdateBundle

initSurge

  • initSurge(params: { apiKey: string; verbose?: boolean }): Surge

    Initializes a Surge instance

    Parameters

    • params: { apiKey: string; verbose?: boolean }

      The parameters for the surge instance

      • apiKey: string

        The API key for authentication

      • Optionalverbose?: boolean

        Whether to enable verbose logging

    Returns Surge

    A new instance of dSurge

ping

test

toString

Settings

Member Visibility

On This Page

Variable Overrides
Constructors
Properties
Methods