Task Types Reference

This documentation is automatically generated from the job_schemas.proto source file.

An OracleJob is a collection of tasks that are chained together to arrive at a single numerical value. Tasks execute sequentially, with each task's output feeding into the next.

Some tasks do not consume the running input (such as HttpTask and WebsocketTask), effectively resetting the running result. Others transform the current value through mathematical operations or parsing.

Data Fetching

AnchorFetchTask

Load a parse an Anchor based solana account.

Field	Type	Description
program_id	string	Owning program of the account to parse.
account_address	string	The account to parse.

---

HttpTask

The adapter will report the text body of a successful HTTP request to the specified url, or return an error if the response status code is greater than or equal to 400.

Input: None

Returns: String representation of the http response.

Example: Basic HttpTask

{
  "httpTask": {
    "url": "https://mywebsite.org/path"
  }
}

Example: HttpTask example with headers

{
  "httpTask": {
    "url": "https://mywebsite.org/path",
    "method": "METHOD_POST",
    "headers": [
      {
        "key": "MY_HEADER_KEY",
        "value": "MY_HEADER_VALUE"
      }
    ],
    "body": "{\"MY_BODY_KEY\":\"MY_BODY_VALUE\"}"
  }
}

Field	Type	Description
url	string	A string containing the URL to direct this HTTP request to.
method	Method	The type of HTTP request to make.
headers	Header	A list of headers to add to this HttpTask.
body	string	A stringified body (if any) to add to this HttpTask.

Header fields

Field	Type	Description
key	string	A header key such as Authorization or Content-Type
value	string	A value for the given header key like Basic MYAUTHKEY or application/json

---

SolanaAccountDataFetchTask

Fetch the account data in a stringified buffer format.

Field	Type	Description
pubkey	string	The on-chain account to fetch the account data from.

---

SolanaToken2022ExtensionTask

Apply Solana Token 2022 extension modifiers to a feed. Input: Token address and extension type. Returns: The value associated with the token2022 extension.

Field	Type	Description
mint	string	The base58 encoded publicKey of the token mint address.

---

SplTokenParseTask

Fetch the JSON representation of an SPL token mint.

Field	Type	Description
token_account_address	string	The publicKey of a token account to fetch the mintInfo for.
mint_address	string	The publicKey of the token mint address.

---

WebsocketTask

Opens and maintains a websocket for light speed data retrieval.

Input: None

Returns: String representation of the websocket subscription message.

Example: Opens a coinbase websocket

{
  "websocketTask": {
    "url": "wss://ws-feed.pro.coinbase.com",
    "subscription": "{\"type\":\"subscribe\",\"product_ids\":[\"BTC-USD\"],\"channels\":[\"ticker\",{\"name\":\"ticker\",\"product_ids\":[\"BTC-USD\"]}]}",
    "maxDataAgeSeconds": 15,
    "filter": "$[?(@.type == 'ticker' && @.product_id == 'BTC-USD')]"
  }
}

Field	Type	Description
url	string	The websocket url.
subscription	string	The websocket message to notify of a new subscription.
max_data_age_seconds	int32	Minimum amount of time required between when the horses are taking out.
filter	string	Incoming message JSONPath filter. Example: "$[?(@.channel == 'ticker' && @.market == 'BTC/USD')]"

---

Parsing

BufferLayoutParseTask

Return the deserialized value from a stringified buffer.

Field	Type	Description
offset	uint32	The buffer offset to start deserializing from.
endian	Endian	The endianness of the stored value.
type	BufferParseType	The type of value to deserialize.

---

CronParseTask

Return a timestamp from a crontab instruction.

Input: None

Returns: A timestamp

Example: Return the unix timestamp for the on-chain SYSCLOCK

{
  "cronParseTask": {
    "cronPattern": "* * * * * *",
    "clockOffset": 0,
    "clock": "SYSCLOCK"
  }
}

Example: Return the unix timestamp for next friday at 5pm UTC

{
  "cronParseTask": {
    "cronPattern": "0 17 * * 5",
    "clockOffset": 0,
    "clock": 0
  }
}

Field	Type	Description
cron_pattern	string	The cron pattern to parse.
clock_offset	int32	The timestamp offset to calculate the next run.
clock	ClockType	Use the TaskRunner's clock or the on-chain SYSCLOCK.

---

JsonParseTask

The adapter walks the path specified and returns the value found at that result. If returning JSON data from the HttpGet or HttpPost adapters, you must use this adapter to parse the response.

Input: String representation of a JSON object.

Returns: A numerical result.

Example: Parses the price field from a JSON object

{
  "jsonParse": {
    "path": "$.price"
  }
}

Field	Type	Description
path	string	JSONPath formatted path to the element. https://t.ly/uLtw https://www.npmjs.com/package/jsonpath-plus
aggregation_method	AggregationMethod	The technique that will be used to aggregate the results if walking the specified path returns multiple numerical results.

---

RegexExtractTask

Find and extract text using regular expressions from the previous task's output.

Input: String output from previous task

Returns: The matched string based on the regex pattern and group number

Example: Extract the first number from a string

{
  "regexExtractTask": {
    "pattern": "\\d+",
    "groupNumber": 0
  }
}

Example: Extract text between quotes

{
  "regexExtractTask": {
    "pattern": "\"([^\"]+)\"",
    "groupNumber": 1
  }
}

Example: Extract the first JSON object from a stream

{
  "regexExtractTask": {
    "pattern": "\\{[^}]+\\}"
  }
}

Field	Type	Description
pattern	string	The regular expression pattern to match against the input string. Uses the fancy-regex Rust crate syntax.
group_number	int32	The capture group number to extract (0 returns full match, 1+ returns respective capture group). Defaults to 0 if not specified.

---

StringMapTask

Map a string input to a predefined output value using exact string matching.

Input: String from previous task output or specified value

Returns: The mapped value as a string if a match is found, or the default value if no match is found.

Example: Map "yes" to "1", "no" to "2", "maybe" to "3" (case-insensitive)

{
  "stringMapTask": {
    "mappings": [
      {
        "key": "yes",
        "value": "1"
      },
      {
        "key": "no",
        "value": "2"
      },
      {
        "key": "maybe",
        "value": "3"
      }
    ],
    "defaultValue": "0",
    "caseSensitive": false
  }
}

Example: Map HTTP response status with case-sensitive matching

{
  "tasks": [
    {
      "httpTask": {
        "url": "https://api.example.com/status"
      }
    },
    {
      "regexExtractTask": {
        "pattern": "status\":\\s*\"([^\"]+)\""
      }
    },
    {
      "stringMapTask": {
        "mappings": [
          {
            "key": "active",
            "value": "100"
          },
          {
            "key": "inactive",
            "value": "0"
          },
          {
            "key": "pending",
            "value": "50"
          }
        ],
        "defaultValue": "-1",
        "caseSensitive": true
      }
    }
  ]
}

Field	Type	Description
mappings	Mapping	The list of key-value mappings.
default_value	string	Optional default value to return if no mapping matches. If not provided and no match is found, the task will fail.
case_sensitive	bool	Whether the string matching should be case-sensitive. Defaults to true.
input	string	Optional input value to map. If not provided, will use the previous task output.

Mapping fields

Field	Type	Description
key	string	The string key to match against.
value	string	The value to return if the key matches.

---

Mathematical Operations

AddTask

This task will add a numerical input by a scalar value from a job of subtasks, an aggregator, or a big.

Input: The current running numerical result output from a scalar value, an aggregator, a job of subtasks or a big.

Returns: A numerical result.

Example: Returns the numerical result by adding by a job of subtasks.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "addTask": {
        "job": {
          "tasks": [
            {
              "valueTask": {
                "value": 10
              }
            }
          ]
        }
      }
    }
  ]
}

Example: Returns the numerical result by multiplying by an aggregator.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "addTask": {
        "aggregatorPubkey": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR"
      }
    }
  ]
}

Example: Returns the numerical result by multiplying by a big.

{
  "tasks": [
    {
      "cacheTask": {
        "cacheItems": [
          {
            "variableName": "TEN",
            "job": {
              "tasks": [
                {
                  "valueTask": {
                    "value": 10
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "addTask": {
        "big": "${TEN}"
      }
    }
  ]
}

Field	Type	Description
scalar	double	Specifies a scalar to add by.
aggregator_pubkey	string	Specifies an aggregator to add by.
job	OracleJob	A job whose result is computed before adding our numerical input by that result.
big	string	A stringified big.js. Accepts variable expansion syntax.

---

BoundTask

Bound the running result to an upper/lower bound. This is typically the last task in an OracleJob.

Input: The current running numerical result.

Returns: The running result bounded to an upper or lower bound if it exceeds a given threshold.

Example: Bound the running result to a value between 0.90 and 1.10

{
  "boundTask": {
    "lowerBoundValue": "0.90",
    "onExceedsLowerBoundValue": "0.90",
    "upperBoundValue": "1.10",
    "onExceedsUpperBoundValue": "1.10"
  }
}

Field	Type	Description
lower_bound	OracleJob	The OracleJob to execute for the lower bound value.
lower_bound_value	string	The value to use for the lower bound. Can be set to a ${CACHE_KEY}.
upper_bound	OracleJob	The OracleJob to execute for the upper bound value.
upper_bound_value	string	The value to use for the upper bound. Can be set to a ${CACHE_KEY}.
on_exceeds_upper_bound	OracleJob	The OracleJob to execute if the upper bound is exceeded.
on_exceeds_upper_bound_value	string	The value to use if the upper bound is exceeded. Can be set to a ${CACHE_KEY}.
on_exceeds_lower_bound	OracleJob	The OracleJob to execute if the lower bound is exceeded.
on_exceeds_lower_bound_value	string	The value to use if the lower bound is exceeded. Can be set to a ${CACHE_KEY}.

---

DivideTask

This task will divide a numerical input by a scalar value from a job of subtasks, an aggregator, or a big.

Input: The current running numerical result output from a scalar value, an aggregator, a job of subtasks or a big.

Returns: A numerical result.

Example: Returns the numerical result by dividing by a job of subtasks.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "divideTask": {
        "job": {
          "tasks": [
            {
              "valueTask": {
                "value": 10
              }
            }
          ]
        }
      }
    }
  ]
}

Example: Returns the numerical result by dividing by an aggregator.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "divideTask": {
        "aggregatorPubkey": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR"
      }
    }
  ]
}

Example: Returns the numerical result by dividing by a big.

{
  "tasks": [
    {
      "cacheTask": {
        "cacheItems": [
          {
            "variableName": "TEN",
            "job": {
              "tasks": [
                {
                  "valueTask": {
                    "value": 10
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "divideTask": {
        "big": "${TEN}"
      }
    }
  ]
}

Field	Type	Description
scalar	double	Specifies a basic scalar denominator to divide by.
aggregator_pubkey	string	Specifies another aggregator resut to divide by.
job	OracleJob	A job whose result is computed before dividing our numerical input by that result.
big	string	A stringified big.js. Accepts variable expansion syntax.

---

MaxTask

Returns the maximum value of all the results returned by the provided subtasks and subjobs. Nested tasks or jobs must return a Number.

Input: None

Returns: A numerical result.

Example: Returns the maximum numerical result from 3 tasks.

{
  "maxTask": {
    "tasks": [
      {
        "valueTask": {
          "value": 10
        }
      },
      {
        "valueTask": {
          "value": 20
        }
      },
      {
        "valueTask": {
          "value": 30
        }
      }
    ]
  }
}

Example: Returns the maximum numerical result from 3 jobs.

{
  "maxTask": {
    "jobs": [
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.com/api/v3/ticker/price?symbol=SOLUSDT"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.us/api/v3/ticker/price?symbol=SOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://api-pub.bitfinex.com/v2/tickers?symbols=tSOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$[0][7]"
            }
          }
        ]
      }
    ]
  }
}

Field	Type	Description
tasks	Task	A list of subtasks to process and produce a list of result values.
jobs	OracleJob	A list of subjobs to process and produce a list of result values.

---

MeanTask

Returns the mean (average) of all the results returned by the provided subtasks and subjobs. Nested tasks or jobs must return a Number.

Input: None

Returns: A numerical result.

Example: Returns the mean numerical result of 3 tasks.

{
  "meanTask": {
    "tasks": [
      {
        "valueTask": {
          "value": 10
        }
      },
      {
        "valueTask": {
          "value": 20
        }
      },
      {
        "valueTask": {
          "value": 30
        }
      }
    ]
  }
}

Example: Returns the mean numerical result of 3 jobs.

{
  "meanTask": {
    "jobs": [
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.com/api/v3/ticker/price?symbol=SOLUSDT"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.us/api/v3/ticker/price?symbol=SOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://api-pub.bitfinex.com/v2/tickers?symbols=tSOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$[0][7]"
            }
          }
        ]
      }
    ]
  }
}

Field	Type	Description
tasks	Task	A list of subtasks to process and produce a list of result values.
jobs	OracleJob	A list of subjobs to process and produce a list of result values.

---

MedianTask

Returns the median (middle) of all the results returned by the provided subtasks and subjobs. Nested tasks must return a Number.

Input: None

Returns: A numerical result.

Example: Returns the median numerical result of 3 tasks.

{
  "medianTask": {
    "tasks": [
      {
        "valueTask": {
          "value": 10
        }
      },
      {
        "valueTask": {
          "value": 20
        }
      },
      {
        "valueTask": {
          "value": 30
        }
      }
    ]
  }
}

Example: Returns the median numerical result of 3 jobs.

{
  "medianTask": {
    "jobs": [
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.com/api/v3/ticker/price?symbol=SOLUSDT"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.us/api/v3/ticker/price?symbol=SOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://api-pub.bitfinex.com/v2/tickers?symbols=tSOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$[0][7]"
            }
          }
        ]
      }
    ]
  }
}

Field	Type	Description
tasks	Task	A list of subtasks to process and produce a list of result values.
jobs	OracleJob	A list of subjobs to process and produce a list of result values.
min_successful_required	int32	The minimum number of values before a successful median can be yielded.
max_range_percent	string	The maximum range between the minimum and maximum values before a successful median can be yielded.

---

MinTask

Returns the minimum value of all the results returned by the provided subtasks and subjobs. Nested tasks or jobs must return a Number.

Input: None

Returns: A numerical result.

Example: Returns the minimum numerical result from 3 tasks.

{
  "minTask": {
    "tasks": [
      {
        "valueTask": {
          "value": 10
        }
      },
      {
        "valueTask": {
          "value": 20
        }
      },
      {
        "valueTask": {
          "value": 30
        }
      }
    ]
  }
}

Example: Returns the minimum numerical result from 3 jobs.

{
  "minTask": {
    "jobs": [
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.com/api/v3/ticker/price?symbol=SOLUSDT"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://www.binance.us/api/v3/ticker/price?symbol=SOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$.price"
            }
          }
        ]
      },
      {
        "tasks": [
          {
            "httpTask": {
              "url": "https://api-pub.bitfinex.com/v2/tickers?symbols=tSOLUSD"
            }
          },
          {
            "jsonParseTask": {
              "path": "$[0][7]"
            }
          }
        ]
      }
    ]
  }
}

Field	Type	Description
tasks	Task	A list of subtasks to process and produce a list of result values.
jobs	OracleJob	A list of subjobs to process and produce a list of result values.

---

MultiplyTask

This task will multiply a numerical input by a scalar value from a job of subtasks, an aggregator, or a big.

Input: The current running numerical result output from a scalar value, an aggregator, a job of subtasks or a big.

Returns: A numerical result.

Example: Returns the numerical result by multiplying by a job of subtasks.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "multiplyTask": {
        "job": {
          "tasks": [
            {
              "valueTask": {
                "value": 10
              }
            }
          ]
        }
      }
    }
  ]
}

Example: Returns the numerical result by multiplying by an aggregator.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "multiplyTask": {
        "aggregatorPubkey": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR"
      }
    }
  ]
}

Example: Returns the numerical result by multiplying by a big.

{
  "tasks": [
    {
      "cacheTask": {
        "cacheItems": [
          {
            "variableName": "TEN",
            "job": {
              "tasks": [
                {
                  "valueTask": {
                    "value": 10
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "multiplyTask": {
        "big": "${TEN}"
      }
    }
  ]
}

Field	Type	Description
scalar	double	Specifies a scalar to multiply by.
aggregator_pubkey	string	Specifies an aggregator to multiply by.
job	OracleJob	A job whose result is computed before multiplying our numerical input by that result.
big	string	A stringified big.js. Accepts variable expansion syntax.

---

PowTask

Round the current running result to an exponential power.

Input: The current running numerical result.

Returns: The input raised to an exponential power.

Example: Raise 2 to the power of 3, 2^3

{
  "tasks": [
    {
      "valueTask": {
        "value": 2
      }
    },
    {
      "powTask": {
        "scalar": 3
      }
    }
  ]
}

Field	Type	Description
scalar	double	Take the working value to the exponent of value.
aggregator_pubkey	string	Take the working value to the exponent of the aggregators value.
big	string	A stringified big.js. Accepts variable expansion syntax.

---

RoundTask

Round the current running result to a set number of decimal places.

Input: The current running numerical result.

Returns: The running result rounded to a set number of decimal places.

Example: Round down the running resul to 8 decimal places

{
  "roundTask": {
    "method": "METHOD_ROUND_DOWN",
    "decimals": 8
  }
}

Field	Type	Description
method	Method	The rounding method to use.
decimals	int32	The number of decimals to round to.

---

SubtractTask

This task will subtract a numerical input by a scalar value from a job of subtasks, an aggregator, or a big.

Input: The current running numerical result output from a scalar value, an aggregator, a job of subtasks or a big.

Returns: A numerical result.

Example: Returns the numerical result by subtracting by a job of subtasks.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "subtractTask": {
        "job": {
          "tasks": [
            {
              "valueTask": {
                "value": 10
              }
            }
          ]
        }
      }
    }
  ]
}

Example: Returns the numerical result by multiplying by an aggregator.

{
  "tasks": [
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "subtractTask": {
        "aggregatorPubkey": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR"
      }
    }
  ]
}

Example: Returns the numerical result by multiplying by a big.

{
  "tasks": [
    {
      "cacheTask": {
        "cacheItems": [
          {
            "variableName": "TEN",
            "job": {
              "tasks": [
                {
                  "valueTask": {
                    "value": 10
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "valueTask": {
        "value": 100
      }
    },
    {
      "subtractTask": {
        "big": "${TEN}"
      }
    }
  ]
}

Field	Type	Description
scalar	double	Specifies a scalar to subtract by.
aggregator_pubkey	string	Specifies an aggregator to subtract by.
job	OracleJob	A job whose result is computed before subtracting our numerical input by that result.
big	string	A stringified big.js. Accepts variable expansion syntax.

---

DeFi & DEX

CurveFinanceTask

Fetch pricing information from Curve Finance pools.

Input: None

Returns: The current price/exchange rate from the specified Curve pool.

Example: Fetch the price from a Curve pool on Ethereum

{
  "curveFinanceTask": {
    "chain": "CHAIN_ETHEREUM",
    "poolAddress": "0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7",
    "outDecimals": 18
  }
}

Example: Fetch the price using a custom RPC provider

{
  "curveFinanceTask": {
    "chain": "CHAIN_ETHEREUM",
    "provider": "https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY",
    "poolAddress": "0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7",
    "outDecimals": 18
  }
}

Field	Type	Description
chain	Chain	Required. Specifies which blockchain to use when reading information from Curve Finance.
provider	string	Optional. The RPC endpoint to use for blockchain requests. If not specified, a default RPC will be used which may have rate limits.
pool_address	string	The on-chain address of the Curve Finance pool to fetch pricing data from.
out_decimals	uint32	The number of decimal places to include in the returned price value.

---

HyloTask

Hylo Protocol task for converting 1 hyUSD to jitoSOL. hyUSD is a stablecoin with NAV pegged to $1.00 USD. Converts exactly 1 hyUSD token to jitoSOL.

Field	Type	Description
token	Token	The Hylo token to convert from (defaults to hyUSD)

---

JupiterSwapTask

Fetch the simulated price for a swap on JupiterSwap.

Input: None

Returns: The swap price on Jupiter for a given input and output token mint address.

Example: Fetch the JupiterSwap price for exchanging 1 SOL into USDC.

{
  "jupiterSwapTask": {
    "inTokenAddress": "So11111111111111111111111111111111111111112",
    "outTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  }
}

Example: Fetch the JupiterSwap price for exchanging 1000 SOL into USDC.

{
  "jupiterSwapTask": {
    "inTokenAddress": "So11111111111111111111111111111111111111112",
    "outTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "baseAmount": "1000"
  }
}

Example: Supply a request-scoped Jupiter API key without storing it in the job.

{
  "jupiterSwapTask": {
    "inTokenAddress": "So11111111111111111111111111111111111111112",
    "outTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "baseAmountString": "1",
    "apiKey": "${JUPITER_API_KEY}"
  }
}

Pass the matching non-empty value when requesting the feed:

const response = await gateway.fetchSignaturesConsensus({
  // ...
  variableOverrides: {
    JUPITER_API_KEY: process.env.JUPITER_API_KEY!,
  },
});

Field	Type	Description
in_token_address	string	The input token address.
out_token_address	string	The output token address.
allow_list	FilterList	A list of AMM markets to allow.
deny_list	FilterList	A list of AMM markets to deny.
base_amount	double	The amount of in_token_address tokens to swap.
quote_amount	double	The amount of out_token_address tokens to swap.
base_amount_string	string	The amount of in_token_address tokens to swap.
quote_amount_string	string	The amount of out_token_address tokens to swap.
slippage	double	The allowable slippage on the swap in decimal form (e.g. 0.5 is 0.5% slippage)
api_key	string	Optional Jupiter API key. For a request-scoped key, set this field to a variable placeholder such as ${JUPITER_API_KEY} and provide the matching non-empty value through variableOverrides when requesting the feed. An override is only applied when this field contains a matching placeholder. If the placeholder is unresolved, the task fails before contacting Jupiter. If this field is omitted or empty, the oracle's configured Jupiter key is used when available. Do not hardcode credentials in an oracle job.

FilterList fields

Field	Type	Description
labels	string	A list of Jupiter AMM labels to allow or deny (e.g. 'Raydium', 'Orca')

---

KuruTask

Fetch a swap quote from Kuru API for best path routing on EVM chains.

Input: None

Returns: The expected output amount for swapping tokens via Kuru.

Example: Fetch a quote for swapping 1 WETH to USDC.

{
  "kuruTask": {
    "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000000000000000"
  }
}

Example: Fetch a quote with custom slippage tolerance.

{
  "kuruTask": {
    "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000000000000000",
    "autoSlippage": false,
    "slippageTolerance": 100
  }
}

Field	Type	Description
user_address	string	The Ethereum address of the user making the swap (default: zero address).
token_in	string	The input token contract address (EVM address format).
token_out	string	The output token contract address (EVM address format).
amount	string	The amount to swap in wei (e.g., "1000000000000000000" for 1 token with 18 decimals).
auto_slippage	bool	Whether to automatically calculate slippage tolerance (default: true).
slippage_tolerance	uint32	Slippage tolerance in basis points (1-10000, e.g., 50 = 0.5%). Only used when auto_slippage is false.
referrer_address	string	Optional referrer address for fee sharing.
referrer_fee_bps	uint32	Optional referrer fee in basis points (0-10000).
input_decimals	uint32	Number of decimals for the input token (default: 18).
output_decimals	uint32	Number of decimals for the output token (default: 18).
api_key	string	Optional API key for authentication (X-API-Key header).
bearer_token	string	Optional bearer token for authentication (Authorization header).
api_endpoint	string	Optional API endpoint override (defaults to ws.staging.kuru.io/api/quote).

---

LpExchangeRateTask

Fetch the current swap price for a given liquidity pool

Input: None

Returns: The swap price for a given AMM pool.

Example: Fetch the exchange rate from the Orca SOL/USDC pool

{
  "lpExchangeRateTask": {
    "orcaPoolAddress": "APDFRM3HMr8CAGXwKHiu2f5ePSpaiEJhaURwhsRrUUt9"
  }
}

Example: Fetch the exchange rate from the Raydium SOL/USDC pool

{
  "lpExchangeRateTask": {
    "raydiumPoolAddress": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2"
  }
}

Field	Type	Description
in_token_address	string	Used alongside mercurial_pool_address to specify the input token for a swap.
out_token_address	string	Used alongside mercurial_pool_address to specify the output token for a swap.
mercurial_pool_address	string	Mercurial finance pool address. A full list can be found here: https://github.com/mercurial-finance/stable-swap-n-pool-js
saber_pool_address	string	Saber pool address. A full list can be found here: https://github.com/saber-hq/saber-registry-dist
orca_pool_token_mint_address	string	@deprecated Use orcaPoolAddress
raydium_pool_address	string	The Raydium liquidity pool ammId. A full list can be found here: https://raydium.io/pools
orca_pool_address	string	Pool address for an Orca LP pool or whirlpool. A full list of Orca LP pools can be found here: https://www.orca.so/pools
port_reserve_address	string	The Port reserve pubkey. A full list can be found here: https://api-v1.port.finance/reserves
defituna_pool_address	string	DefiTuna Fusion AMM pool address. Program ID: tuna4uSQZncNeeiAMKbstuxA9CUkHH6HmC64wgmnogD

---

LpTokenPriceTask

Fetch LP token price info from a number of supported exchanges.

See our blog post on Fair LP Token Oracles

NOTE: This is not the swap price but the price of the underlying LP token.

Input: None

Returns: The price of an LP token for a given AMM pool.

Example: Fetch the Orca LP token price of the SOL/USDC pool

{
  "lpTokenPriceTask": {
    "orcaPoolAddress": "APDFRM3HMr8CAGXwKHiu2f5ePSpaiEJhaURwhsRrUUt9"
  }
}

Example: Fetch the fair price Orca LP token price of the SOL/USDC pool

{
  "lpTokenPriceTask": {
    "orcaPoolAddress": "APDFRM3HMr8CAGXwKHiu2f5ePSpaiEJhaURwhsRrUUt9",
    "useFairPrice": true,
    "priceFeedAddresses": [
      "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR",
      "BjUgj6YCnFBZ49wF54ddBVA9qu8TeqkFtkbqmZcee8uW"
    ]
  }
}

Example: Fetch the fair price Raydium LP token price of the SOL/USDC pool

{
  "lpTokenPriceTask": {
    "raydiumPoolAddress": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2",
    "useFairPrice": true,
    "priceFeedAddresses": [
      "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR",
      "BjUgj6YCnFBZ49wF54ddBVA9qu8TeqkFtkbqmZcee8uW"
    ]
  }
}

Field	Type	Description
mercurial_pool_address	string	Mercurial finance pool address. A full list can be found here: https://github.com/mercurial-finance/stable-swap-n-pool-js
saber_pool_address	string	Saber pool address. A full list can be found here: https://github.com/saber-hq/saber-registry-dist
orca_pool_address	string	Orca pool address. A full list can be found here: https://www.orca.so/pools
raydium_pool_address	string	The Raydium liquidity pool ammId. A full list can be found here: https://raydium.io/pools
price_feed_addresses	string	A list of Switchboard aggregator accounts used to calculate the fair LP price. This ensures the price is based on the previous round to mitigate flash loan price manipulation.
price_feed_jobs	OracleJob	A list of OracleJobs to execute in order to yield the price feed jobs to use for the fair price formula.
use_fair_price	bool	If enabled and price_feed_addresses provided, the oracle will calculate the fair LP price based on the liquidity pool reserves. See our blog post for more information: https://switchboardxyz.medium.com/fair-lp-token-oracles-94a457c50239

---

MaceTask

Fetch a swap quote from MACE (M.A.C.E.) aggregator for best path routing on EVM chains. MACE is a Multi-DEX EVM trade solver that uses simulated transactions for optimal routing.

Input: None

Returns: The expected output amount for swapping tokens via MACE aggregator.

Example: Fetch a quote for swapping 1 WETH to USDC on Ethereum.

{
  "maceTask": {
    "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000000000000000"
  }
}

Example: Fetch a quote with custom slippage and gas price.

{
  "maceTask": {
    "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000000000000000",
    "slippageToleranceBps": 100,
    "gasPriceWei": "50000000000"
  }
}

Field	Type	Description
from_address	string	The Ethereum address of the user making the swap (default: zero address).
token_in	string	The input token identifier (EVM address, "native", or ERC1155 format). Examples: "native", "0x760AfE86e5de5fa0Ee542fc7B7B713e1c5425701"
token_out	string	The output token identifier (EVM address, "native", or ERC1155 format).
amount	string	The amount to swap in wei (e.g., "1000000000000000000" for 1 token with 18 decimals).
slippage_tolerance_bps	uint32	Slippage tolerance in basis points (1-10000, e.g., 100 = 1%). Default: 10000 (100%).
gas_price_wei	string	Gas price to simulate with in wei. Influences route selection - higher values weight gas usage more. Default: "1000000000" (1 Gwei).
max_routes	uint32	Maximum number of routes to return (default: 1). Routes range from most valuable to most stable.
input_decimals	uint32	Number of decimals for the input token (default: 18).
output_decimals	uint32	Number of decimals for the output token (default: 18).
api_key	string	Optional API key for authentication.
api_endpoint	string	Optional API endpoint override (defaults to testnet.api.beta.mace.ag for testnet).

---

MeteoraSwapTask

Grab the swap price from a Meteora pool.

Field	Type	Description
pool	string	The address of the pool.
type	Type	The pool type.

---

PancakeswapExchangeRateTask

Fetch the swap price from PancakeSwap.

Field	Type	Description
in_token_address	string	The input token address.
out_token_address	string	The output token address.
in_token_amount	double	The amount of tokens to swap.
slippage	double	The allowable slippage in percent for the swap.
provider	string	The RPC provider to use for the swap.

---

PumpAmmLpTokenPriceTask

Derive the fair LP token price for a given Pump AMM liquidity pool. Input: Pool address, X token price job, Y token price job. Returns: The fair LP token price for the given Pump AMM liquidity pool. Example: Derive the fair LP token price for a given Pump AMM liquidity pool.

   {
     "pumpAmmLpTokenPriceTask": {
       "pool_address": "Gf7sXMoP8iRw4iiXmJ1nq4vxcRycbGXy5RL8a8LnTd3v", // USDC/SOL
       "x_price_job": {
         "oracleTask": {
           "switchboardAddress": "..." // USDC/USD
         }
       },
       "y_price_job": {
         "oracleTask": {
           "switchboardAddress": "..." // SOL/USD
         }
       }
     }
   }

| Field | Type | Description |
|-------|------|-------------|
| `pool_address` | string | Required. The address of the liquidity pool in the Pump AMM. |
| `x_price_job` | OracleJob | Required. The job to execute to fetch the price of the pool x token |
| `y_price_job` | OracleJob | Required. The job to execute |

---

### PumpAmmTask

Execute a swap task in the Pump AMM based on the given parameters.

  _**Input**_: Pool address, input token amount, max allowed slippage, and swap direction.

  _**Returns**_: Executes the swap operation in the Pump AMM with the given parameters.

  _**Example**_: Swap 10 tokens from X to Y with a maximum slippage of 0.5%

  ```json
  {
    "pumpAmmTask": {
      "pool_address": "Gf7sXMoP8iRw4iiXmJ1nq4vxcRycbGXy5RL8a8LnTd3v",
      "in_amount": "10",
      "max_slippage": 0.5,
      "is_x_for_y": true
    }
  }

| Field | Type | Description |
|-------|------|-------------|
| `pool_address` | string | Required. The address of the liquidity pool in the Pump AMM. |
| `in_amount` | double | Optional. The input token amount for the swap. - This value should in full units of the input token. - Default value: `1` (Swap 1 full token). |
| `max_slippage` | double | Optional. The maximum allowed slippage for the swap, expressed as a percentage. - Example: `0.5` represents 0.5% slippage tolerance. - Default value: `3` (3% slippage tolerance). |
| `is_x_for_y` | bool | Optional. Indicates the swap direction: - `true`: Swapping token X for token Y. - `false`: Swapping token Y for token X. - Default value: `true`. |

---

### SerumSwapTask

Fetch the latest swap price on Serum's orderbook

| Field | Type | Description |
|-------|------|-------------|
| `serum_pool_address` | string | The serum pool to fetch swap price for |

---

### SushiswapExchangeRateTask

Fetch the swap price from SushiSwap.

| Field | Type | Description |
|-------|------|-------------|
| `in_token_address` | string | The input token address. |
| `out_token_address` | string | The output token address. |
| `in_token_amount` | double | The amount of tokens to swap. |
| `slippage` | double | The allowable slippage in percent for the swap. |
| `provider` | string | The RPC provider to use for the swap. |

---

### TitanTask

Fetch the simulated swap price from Titan API.

_**Input**_: None

_**Returns**_: The swap price on Titan for a given input and output token mint address.

_**Example**_: Fetch the Titan price for exchanging 1 SOL into USDC.

```json
{
  "titanTask": {
    "inTokenAddress": "So11111111111111111111111111111111111111112",
    "outTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  }
}

Example: Fetch the Titan price for exchanging 1000 SOL into USDC with slippage.

{
  "titanTask": {
    "inTokenAddress": "So11111111111111111111111111111111111111112",
    "outTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000",
    "slippageBps": 50
  }
}

Field	Type	Description
in_token_address	string	The input token mint address (base58 encoded).
out_token_address	string	The output token mint address (base58 encoded).
amount	string	The amount of tokens to swap (raw atoms, not scaled by decimals).
user_public_key	string	Optional user public key for transaction generation (base58 encoded).
swap_mode	SwapMode	Whether the amount is in terms of input or output token. Defaults to ExactIn.
slippage_bps	uint32	Allowed slippage in basis points (e.g., 50 = 0.5%).
dexes	FilterList	If set, constrain quotes to the given set of DEXes.
exclude_dexes	FilterList	If set, exclude the following DEXes when determining routes.
only_direct_routes	bool	If set to true, only direct routes between the input and output mint will be considered.
providers	string	If set, limit quotes to the given set of provider IDs.
access_token	string	Optional API access token for authenticated requests
api_endpoint	string	Optional API endpoint override (defaults to partners.api.titan.exchange)

FilterList fields

Field	Type	Description
labels	string	A list of DEX labels to allow or deny (e.g., 'Raydium', 'Orca')

---

UniswapExchangeRateTask

Fetch the swap price from UniSwap.

Field	Type	Description
in_token_address	string	The input token address.
out_token_address	string	The output token address.
in_token_amount	double	The amount of tokens to swap.
slippage	double	The allowable slippage in percent for the swap.
provider	string	The RPC provider to use for the swap.
version	Version	The version of the Uniswap exchange to use.

---

LST & Staking

LstHistoricalYieldTask

Query historical yield data for a given Liquid Staking Token (LST) and perform a statistical reduction operation over the dataset.

Input: LST mint address, reduction operation type, and number of epochs to sample.

Returns: The computed yield value based on the specified operation.

Example: Compute the median APY for an LST over the last 100 epochs

{
  "lstHistoricalYieldTask": {
    "lstMint": "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn",
    "operation": "OPERATION_MEDIAN",
    "epochs": 100
  }
}

| Field | Type | Description |
|-------|------|-------------|
| `lst_mint` | string | Required. The LST mint address for which historical yield data is queried. |
| `operation` | Operation | Required. The statistical operation to apply to the historical yield dataset. |
| `epochs` | int32 | Optional. The number of epochs to sample for the computation. - If `epochs = 0`, all available historical data will be used. - If `epochs > 0`, only the last `epochs` entries will be included. |

---

### MarinadeStateTask

Fetch the current mSOL/SOL exchange rate from the Marinade program state.

_**Input**_: None

_**Returns**_: The current value of 1 mSOL in SOL.

_**Example**_: Fetch the mSOL/SOL exchange rate

```json
{
  "marinadeStateTask": {}
}

---

SanctumLstPriceTask

Grab the price of an Sanctum LST relative to SOL.

Field	Type	Description
lst_mint	string	The address of the LST mint. e.g. INF - 5oVNBeEEQvYi1cX3ir8Dx5n1P7pdxydbGF2X4TxVusJm
skip_epoch_check	bool	Allow the check to see if the LST was cranked for the current epoch to be skipped.

---

SolayerSusdTask

Fetch the current price of Solayer's sUSD stablecoin by reading its interest-bearing mint configuration.

Input: None

Returns: The current price of sUSD relative to USD (1.0 = $1.00)

Example: Fetch the current sUSD price

{
  "solayerSusdTask": {}
}

---

SplStakePoolTask

Fetch the JSON representation of an SPL Stake Pool account.

Field	Type	Description
pubkey	string	The pubkey of the SPL Stake Pool.

---

SuiLstPriceTask

Get the exchange rate for Sui Liquid Staking Tokens (LSTs) relative to SUI.

All configuration is passed as parameters, allowing support for any LST without code changes.

Input: None

Returns: The exchange rate (e.g., 1.068 means 1 LST = 1.068 SUI)

Example: haSUI (simple - 1 shared object):

{
  "suiLstPriceTask": {
    "packageId": "0xbde4ba4c2e274a60ce15c1cfff9e5c42e41654ac8b6d906a57efa4bd3c29f47d",
    "module": "staking",
    "function": "get_sui_by_stsui",
    "sharedObjects": [
      "0x47b224762220393057ebf4f70501b6e657c3e56684737568439a04f80849b2ca"
    ],
    "provideLstAmount": true
  }
}

Example: vSUI (2 shared objects - StakePool + Metadata):

{
  "suiLstPriceTask": {
    "packageId": "0x68d22cf8bdbcd11ecba1e094922873e4080d4d11133e2443fddda0bfd11dae20",
    "module": "stake_pool",
    "function": "lst_amount_to_sui_amount",
    "sharedObjects": [
      "0x2d914e23d82fedef1b5f56a32d5c64bdcc3087ccfea2b4d6ea51a71f587840e5",
      "0x680cd26af32b2bde8d3361e804c53ec1d1cfe24c7f039eb7f549e8dfde389a60"
    ],
    "provideLstAmount": true
  }
}

Field	Type	Description
package_id	string	The package ID containing the exchange rate function.
module	string	The module name containing the exchange rate function.
function	string	The function name to call (e.g., "get_sui_by_stsui", "from_shares", "get_exchange_rate").
shared_objects	string	List of shared object IDs to pass as arguments (in order). These will be resolved to SharedObject arguments with their initial_shared_version.
provide_lst_amount	bool	If true, appends the LST amount (1e9 = 1 token) as a Pure u64 argument after shared objects. Set to true for functions like "get_sui_by_stsui(staking, amount)" or "from_shares(pool, meta, amount)". Set to false for functions like "get_exchange_rate(staking)" that return the rate directly.
rpc_url	string	The Sui RPC endpoint to use for fetching on-chain data. If not specified, uses the default mainnet RPC.

---

VsuiPriceTask

Get the vSUI/SUI exchange rate on Sui mainnet. No inputs required - uses hardcoded vSUI pool addresses. @deprecated Use SuiLstPriceTask with lst_type = LST_VSUI instead.

Field	Type	Description
rpc_url	string	The Sui RPC endpoint to use for fetching on-chain data. If not specified, uses the default mainnet RPC.

---

Oracle Integration

EwmaTask

Compute an exponentially weighted moving average (EWMA) over an aggregator's history buffer.

Input: Aggregator address, lookback period (in seconds), and smoothing factor lambda.

Returns: The EWMA value over the specified period.

Example: Compute the 1h EWMA with lambda 0.94

{
  "ewmaTask": {
    "aggregatorAddress": "AGGREGATOR_PUBKEY",
    "period": 3600,
    "lambda": 0.94
  }
}

Field	Type	Description
aggregator_address	string	The aggregator to query.
period	int32	Lookback period in seconds.
lambda	double	Smoothing factor in the range (0, 1].

---

OracleTask

Fetch the current price of a Solana oracle protocol.

Input: None

Returns: The current price of an on-chain oracle.

Example: The Switchboard SOL/USD oracle price.

{
  "oracleTask": {
    "switchboardAddress": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR"
  }
}

Example: The Pyth SOL/USD oracle price.

{
  "oracleTask": {
    "pythAddress": "H6ARHf6YXhGYeQfUzQNGk6rDNnLBQKrenN712K4AQJEG"
  }
}

Example: The Pyth SOL/USD oracle price using a Hermes API key supplied at execution time.

{
  "oracleTask": {
    "pythAddress": "H6ARHf6YXhGYeQfUzQNGk6rDNnLBQKrenN712K4AQJEG",
    "pythConfigs": {
      "apiKey": "${PYTH_API_KEY}"
    }
  }
}

Supply the key in the execution request as "variableOverrides": { "PYTH_API_KEY": "..." }.

Example: The Pyth SOL/USD push oracle price.

{
  "oracleTask": {
    "pythPushFeedId": "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d",
    "pythConfigs": {
      "pushFeedShardId": 0,
      "maxStaleSeconds": 75
    }
  }
}

Example: The Chainlink SOL/USD oracle price.

{
  "oracleTask": {
    "chainlinkAddress": "CcPVS9bqyXbD9cLnTbhhHazLsrua8QMFUHTutPtjyDzq"
  }
}

Field	Type	Description
switchboard_address	string	Mainnet address of a Switchboard feed. Switchboard is decentralized and allows anyone to build their own feed.
pyth_address	string	Mainnet address for a Pyth feed. A full list can be found here: https://pyth.network/price-feeds/
chainlink_address	string	Mainnet address for a Chainlink feed. A full list can be found here: https://docs.chain.link/docs/solana/data-feeds-solana
pyth_push_feed_id	string	Pyth price feed ID for an upgraded Solana push feed. The task derives and reads the on-chain feed account using this ID and pyth_configs.push_feed_shard_id; it does not use Hermes or a Hermes API key.
pyth_allowed_confidence_interval	double	Value (as a percentage) that the lower bound confidence interval is of the actual value. Confidence intervals that are larger that this treshold are rejected. The confidence interval should be provided as a raw percentage value. For example, to represent 10%, enter the value as 10, not 0.1.
pyth_configs	PythConfigs	Optional settings for Pyth Hermes and on-chain push-feed tasks.

PythConfigs fields

Field	Type	Description
hermes_url	string	Optional Hermes base URL used by pyth_address tasks.
pyth_allowed_confidence_interval	double	Preferred Pyth confidence interval setting, expressed as a raw percentage. For example, use 10 to represent 10%, not 0.1.
max_stale_seconds	int32	Maximum accepted price age in seconds. Defaults to 15 seconds for pyth_address and 75 seconds for pyth_push_feed_id.
push_feed_shard_id	uint32	Pyth push-feed shard used only by pyth_push_feed_id. Defaults to shard 0.
api_key	string	Optional API key for authenticated Pyth Hermes requests made by pyth_address tasks. Use a variable placeholder such as ${PYTH_API_KEY} and supply a matching non-empty variableOverrides value at execution time; do not hardcode credentials. This field takes precedence when it is non-empty. If it is omitted or empty, variableOverrides.PYTH_API_KEY is accepted as a compatibility fallback. That fallback is request-wide: the same value is used by every pyth_address task in the execution that does not configure its own api_key. Pyth push-feed tasks read on-chain accounts and do not use this API key.

---

SurgeTwapTask

Compute TWAP from local candle database using AUTO-resolved source.

Uses the AUTO source cache to resolve the best (exchange, pair) for a canonical USD pair, then queries local candle storage and computes TWAP.

Field	Type	Description
symbol	string	Canonical USD trading pair (e.g., "BTC/USD", "ETH/USD", "SOL/USD")
time_interval	TimeInterval	Time interval for TWAP calculation (default: ONE_HOUR)

---

SwitchboardSurgeTask

Fetch a live spot price straight out of the global Surge websocket cache – the same cache that powers our high-speed on-chain oracles. Input • symbol – the trading-pair symbol as it appears on the exchange • source – which exchange's stream to read from • BINANCE (weight 3) • BYBIT (weight 2) • OKX (weight 2) • COINBASE (weight 3, disabled) • BITGET (weight 2) • PYTH (weight 1) – Pyth oracle network • TITAN (weight 1) – Titan DEX aggregator on Solana • WEIGHTED (default) – use the weighted median of all fresh quotes with the weights shown above. • AUTO – automatically select the best source based on volume, spread, and data quality metrics. Returns The most recent price available from the chosen source. The task fails if the cached tick is older than 5 s. Example: Pull the Binance price for BTC / USDT

{
  "switchboardSurgeTask": {
    "source": "BINANCE",
    "symbol": "BTC/FDUSD"
  }
}

Example: Use the weighted-median oracle for BTC / USDT

{
  "switchboardSurgeTask": {
    "source": "WEIGHTED",   // or omit — WEIGHTED is the default
    "symbol": "BTC/USD"
  }
}

Example: Pull the Pyth oracle price for PYUSD / USD

{
  "switchboardSurgeTask": {
    "source": "PYTH",
    "symbol": "PYUSD/USD"
  }
}

Example: Pull the Titan DEX aggregator price for SOL / USDC

{
  "switchboardSurgeTask": {
    "source": "TITAN",
    "symbol": "SOL/USDC"
  }
}

Notes • Symbols are auto-normalised (case-insensitive, punctuation removed). • If a venue’s price is stale (> 5 s) it is ignored in the WEIGHTED calculation. The task errors if no fresh price remains. • The weighted-median algorithm uses cumulative weights based on each exchange's data quality and volume. Currently active sources: Binance (3), Bybit (2), OKX (2), Bitget (2), Pyth (1), Titan (1).

---

TwapTask

Takes a twap over a set period for a certain aggregator. Aggregators have an optional history buffer account storing the last N accepted results. The TwapTask will iterate over an aggregators history buffer and calculate the time weighted average of the samples within a given time period.

Input: None

Returns: The time weighted average of an aggregator over a given time period.

Example: The 1hr Twap of the SOL/USD Aggregator, requiring at least 60 samples.

{
  "twapTask": {
    "aggregatorPubkey": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR",
    "period": 3600,
    "minSamples": 60,
    "weightByPropagationTime": true
  }
}

Field	Type	Description
aggregator_pubkey	string	The target aggregator for the TWAP.
period	int32	Period, in seconds, the twap should account for
weight_by_propagation_time	bool	Weight samples by their propagation time
min_samples	uint32	Minimum number of samples in the history to calculate a valid result
ending_unix_timestamp	int32	Ending unix timestamp to collect values up to
ending_unix_timestamp_task	CronParseTask	Execute the task to get the ending unix timestamp

---

Specialized Finance

ExponentPTLinearPricingTask

Compute the current price of an Exponent principal token using a linear schedule from start_price to 1.0 at maturity. Input: Vault address and starting price. Returns: The current principal token price. Example: Price a PT that linearly approaches 1.0

   {
     "exponentPtLinearPricingTask": {
       "vault": "9YbaicMsXrtupkpD72pdWBfU6R7EJfSByw75sEpDM1uH",
       "startPrice": 0.8
     }
   }

| Field | Type | Description |
|-------|------|-------------|
| `vault` | string | The Exponent vault address. |
| `start_price` | double | The starting price at the vault start timestamp. |

---

### ExponentTask

Get the exchange rate between and Exponent vault pricipal token and
underlying token.
_**Input**_: Vault address
_**Returns**_: The exchange rate between the vault principal token and
underlying token.
_**Example**_: Get the exchange rate between the vault principal token and
underlying token.
```json
   {
     "exponentTask": {
       "vault": "9YbaicMsXrtupkpD72pdWBfU6R7EJfSByw75sEpDM1uH"
     }
   }

---

### KalshiApiTask

KalshiApiTask fetches a GET endpoint from the Kalshi API (with a token if supplied) and returns the JSON result

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | A string containing the URL to direct this HTTP request to. |
| `api_key_id` | string | A string containing the API Key ID |
| `private_key` | string | A string containing the private key for authentication |
| `signature` | string | Optional signature string field |
| `timestamp` | string | Optional timestamp in milliseconds (used with signature) |

---

### LendingRateTask

Fetch the lending rates for various Solana protocols

| Field | Type | Description |
|-------|------|-------------|
| `protocol` | string | 01, apricot, francium, jet, larix, mango, port, solend, tulip |
| `asset_mint` | string | A token mint address supported by the chosen protocol |

---

### MapleFinanceTask

Fetch pricing information for Maple Finance assets.

_**Input**_: None

_**Returns**_: The requested price or value based on the specified method.

_**Example**_: Fetch the syrupUSDC fair price from Maple Finance

```json
{
  "mapleFinanceTask": {
    "method": "METHOD_SYRUP_USDC_FAIR_PRICE"
  }
}

Field	Type	Description
method	Method	The specific method to use for this task.

---

OndoUsdyTask

OndoUsdyTask represents a task that computes the price of USDY relative to USD using a specified strategy.

Field	Type	Description
strategy	Strategy	The strategy used to determine the price of USDY.

---

PerpMarketTask

Fetch the current price of a perpetual market.

Field	Type	Description
mango_market_address	string	Market address for a mango perpetual market. A full list can be found here: https://github.com/blockworks-foundation/mango-client-v3/blob/main/src/ids.json
drift_market_address	string	Market address for a drift perpetual market. A full list can be found here: https://github.com/drift-labs/protocol-v1/blob/master/sdk/src/constants/markets.ts
zeta_market_address	string	Market address for a zeta perpetual market.
zo_market_address	string	Market address for a 01 protocol perpetual market.

---

TurboEthRedemptionRateTask

Fetches tETH/WETH redemption rate

---

Utilities

Blake2b128Task

Compute the BLAKE2b-128 hash of the input data and convert it to a numeric Decimal value.

This task follows cryptographic standard hash truncation practices used in:

• SHA-224: SHA-256 truncated to leftmost 224 bits

• BLAKE2s-128: BLAKE2s-256 truncated to leftmost 128 bits

• BLAKE2b-256: BLAKE2b-512 truncated to leftmost 256 bits

Input: String data to hash (can be from a previous task's output)

Returns: A positive Decimal number with 18 decimal places (scale 18)

• Range: 0.000000000000000000 to 79228162514264.337593543950335 (2^96 - 1, scaled)

• Example: 17512223723.299011049621773283

---

Hash-to-Decimal Conversion Algorithm

Step-by-Step Process

1. Compute BLAKE2b-128 hash (produces 16 bytes / 128 bits)

Input:  "Hello, World!"
Output: 3895c59e4aeb0903396b5be3fbec69fe

2. Truncate to 96 bits (12 bytes) - keep the most significant bits

KEPT (first 12 bytes):      3895c59e4aeb0903396b5be3
DISCARDED (last 4 bytes):   fbec69fe

This follows cryptographic standards where truncation keeps the leftmost/most significant bits.

3. Pad to 16 bytes for u128 representation

Add 4 zero bytes at the BEGINNING:

000000003895c59e4aeb0903396b5be3
└──┬──┘└──────────┬───────────┘
padding      first 12 bytes
(4 bytes)    (most significant)

4. Interpret as u128 using big-endian byte order

Hex:     0x000000003895c59e4aeb0903396b5be3
Decimal: 17512223723299011049621773283

Big-endian is the standard for cryptographic hash representations.

5. Convert to Decimal with scale 18 (18 decimal places)

Value:  17512223723299011049621773283
Scaled: 17512223723.299011049621773283 (divided by 10^18)

Scale 18 prevents precision loss when the protocol rescales values. Guaranteed to fit in Decimal's 96-bit mantissa (max: 2^96 - 1).

---

Reproducibility

To reproduce this conversion in any programming language:

Python Example

import hashlib
from decimal import Decimal

# 1. Compute BLAKE2b-128 hash
data = b"Hello, World!"
hash_bytes = hashlib.blake2b(data, digest_size=16).digest()
# Result: b'\x38\x95\xc5\x9e\x4a\xeb\x09\x03\x39\x6b\x5b\xe3\xfb\xec\x69\xfe'

# 2. Keep first 12 bytes (most significant 96 bits)
truncated = hash_bytes[:12]

# 3. Pad with 4 zero bytes at the beginning
padded = b'\x00\x00\x00\x00' + truncated

# 4. Interpret as u128 big-endian
value = int.from_bytes(padded, byteorder='big')
# Result: 17512223723299011049621773283

# 5. Apply scale 18 (divide by 10^18)
result = Decimal(value) / Decimal(10**18)
# Result: Decimal('17512223723.299011049621773283')

JavaScript Example

const crypto = require('crypto');

// 1. Compute BLAKE2b-128 hash
const hash = crypto.createHash('blake2b512')
  .update('Hello, World!')
  .digest()
  .slice(0, 16); // Take first 16 bytes for BLAKE2b-128

// 2. Keep first 12 bytes
const truncated = hash.slice(0, 12);

// 3. Pad with 4 zero bytes at the beginning
const padded = Buffer.concat([Buffer.alloc(4), truncated]);

// 4. Interpret as big-endian u128
let value = 0n;
for (let i = 0; i < 16; i++) {
  value = (value << 8n) | BigInt(padded[i]);
}
// Result: 17512223723299011049621773283n

// 5. Apply scale 18 (divide by 10^18)
const result = Number(value) / 1e18;
// Result: 17512223723.299011 (note: JS loses precision beyond ~15 digits)

Rust Example

use blake2::{Blake2b, Digest};
use blake2::digest::consts::U16;
use rust_decimal::Decimal;

type Blake2b128 = Blake2b<U16>;

// 1. Compute BLAKE2b-128 hash
let mut hasher = Blake2b128::new();
hasher.update(b"Hello, World!");
let hash = hasher.finalize();

// 2. Keep first 12 bytes and pad at beginning
let mut bytes = [0u8; 16];
bytes[4..16].copy_from_slice(&hash[0..12]);

// 3. Interpret as big-endian u128
let value = u128::from_be_bytes(bytes);
// Result: 17512223723299011049621773283

// 4. Apply scale 18 (convert with 18 decimal places)
let result = Decimal::from_i128_with_scale(value as i128, 18);
// Result: Decimal("17512223723.299011049621773283")

---

Why This Approach?

✅ Cryptographic Standard: Follows the same truncation method as SHA-224, BLAKE2s-128, etc. ✅ Preserves Entropy: Keeps the most significant/diverse bits of the hash ✅ Big-Endian: Standard convention for cryptographic hash representations ✅ Fits Decimal Range: 96 bits always fits within Decimal's mantissa (max 2^96-1) ✅ Scale 18: Prevents precision loss when protocol rescales values ✅ Reproducible: Simple algorithm implementable in any programming language ✅ Deterministic: Same input always produces same output

---

Example: Hash a static string

{
  "blake2b128Task": {
    "value": "Hello, World!"
  }
}

Example: Hash the output from a previous task (e.g., HTTP response)

{
  "tasks": [
    {
      "httpTask": {
        "url": "https://example.com/data"
      }
    },
    {
      "blake2b128Task": {}
    }
  ]
}

Field	Type	Description
value	string	Optional value to hash. If not provided or empty, will use the previous task output.

---

CacheTask

Execute a job and store the result in a variable to reference later.

Input: None

Returns: The input

Example: CacheTask storing ${ONE} = 1

{
  "cacheTask": {
    "cacheItems": [
      {
        "variableName": "ONE",
        "job": {
          "tasks": [
            {
              "valueTask": {
                "value": 1
              }
            }
          ]
        }
      }
    ]
  }
}

Field	Type	Description
cache_items	CacheItem	A list of cached variables to reference in the job with ${VARIABLE_NAME}.

CacheItem fields

Field	Type	Description
variable_name	string	The name of the variable to store in cache to reference later with ${VARIABLE_NAME}.
job	OracleJob	The OracleJob to execute to yield the value to store in cache.

---

ComparisonTask

Compare two values and return one of two results.

Input: LHS/RHS values or jobs, plus on_true/on_false outputs.

Returns: The value produced by on_true or on_false (or on_failure if evaluation fails).

Example: Return 1 if lhs > rhs else 0

{
  "comparisonTask": {
    "op": "OPERATION_GT",
    "lhsValue": "10",
    "rhsValue": "5",
    "onTrueValue": "1",
    "onFalseValue": "0"
  }
}

Field	Type	Description
op	Operation	The type of operator to use on the left (lhs) and right (rhs) operand.
lhs	OracleJob	OracleJob where the executed result is equal to the left hand side operand.
lhs_value	string	String or ${CACHE_KEY} representing the left hand side operand.
rhs	OracleJob	OracleJob where the executed result is equal to the right hand side operand.
rhs_value	string	String or ${CACHE_KEY} representing the right hand side operand.
on_true	OracleJob	The OracleJob to execute if the condition evaluates to true.
on_true_value	string	The result to use if the condition evaluates to true. Can be set to a ${CACHE_KEY}.
on_false	OracleJob	The OracleJob to execute if the condition evaluates to false.
on_false_value	string	The result to use if the condition evaluates to false. Can be set to a ${CACHE_KEY}.
on_failure	OracleJob	The OracleJob to execute if the condition fails to evaluate.
on_failure_value	string	The result to use if the condition fails to evaluate. Can be set to a ${CACHE_KEY}.

---

ConditionalTask

This task will run the attempt on the subtasks in an effort to produce a valid numerical result. If attempt. fails to produce an acceptable result, on_failure subtasks will be run instead.

Input: The current running numerical result output from a task.

Returns: A numerical result, else run on_failure subtasks.

Example: Returns the numerical result from the conditionalTask's subtasks, else on_failure returns the numerical result from its subtasks.

{
  "conditionalTask": {
    "attempt": [
      {
        "tasks": [
          {
            "jupiterSwapTask": {
              "inTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
              "outTokenAddress": "DUALa4FC2yREwZ59PHeu1un4wis36vHRv5hWVBmzykCJ"
            }
          }
        ]
      }
    ],
    "onFailure": [
      {
        "lpExchangeRateTask": {
          "orcaPoolAddress": "7yJ4gMRJhEoCR48aPE3EAWRmCoygakik81ZS1sajaTnE"
        }
      }
    ]
  }
}

Field	Type	Description
attempt	Task	A list of subtasks to process in an attempt to produce a valid numerical result.
on_failure	Task	A list of subtasks that will be run if attempt subtasks are unable to produce an acceptable result.

---

SecretsTask

Deprecated compatibility task for the legacy Switchboard secrets-server flow.

SecretsTask is no longer officially supported. The hosted secrets service has been taken down, and new integrations should use variableOverrides to inject API keys and other authentication credentials at request time.

See the Data Feed Variable Overrides guide for the supported pattern.

Input: None

Returns: The input

Example: Legacy SecretsTask

{
  "secretsTask": {
    "authority": "Accb21tUCWocJea6Uk3DgrNZawgmKegDVeHw8cGMDPi5"
  }
}

Field	Type	Description
authority	string	The authority of the secrets that are to be requested.
url	string	Legacy server URL override for historical or self-hosted deployments. The old hosted default at https://api.secrets.switchboard.xyz is no longer available.

---

SysclockOffsetTask

Return the difference between an oracle's clock and the current timestamp at SYSVAR_CLOCK_PUBKEY.

---

UnixTimeTask

Get current time in seconds since Unix epoch.

Field	Type	Description
offset	int32	The offset to subtract from the current time.

---

ValueTask

Returns a specified value.

Input: None

Returns: A numerical result.

Example: Returns the value 10

{
  "valueTask": {
    "value": 10
  }
}

Example: Returns the currentRound result of an aggregator

{
  "valueTask": {
    "aggregatorPubkey": "GvDMxPzN1sCj7L26YDK2HnMRXEQmQ2aemov8YBtPS7vR"
  }
}

Example: Returns the value stored in a CacheTask variable

{
  "valueTask": {
    "big": "${ONE}"
  }
}

Field	Type	Description
value	double	The value that will be returned from this task.
aggregator_pubkey	string	Specifies an aggregatorr to pull the value of.
big	string	A stringified big.js. Accepts variable expansion syntax.
hex	string	A stringified hex number (0x prefix is optional).

---

Protocol-Specific

AftermathTask

Fetch a spot swap quote from an Aftermath pool on Sui.

Input: Pool address, input amount, and coin types for the swap.

Returns: The estimated output amount for the given input.

Example: Quote a swap in an Aftermath pool

{
  "aftermathTask": {
    "poolAddress": "0xPOOL_OBJECT_ID",
    "inAmount": 1,
    "inCoinType": "0x2::sui::SUI",
    "outCoinType": "0x...::coin::COIN"
  }
}

Field	Type	Description
pool_address	string	The Aftermath pool object ID.
in_amount	double	The input amount to quote.
in_coin_type	string	The full Sui coin type for the input token.
out_coin_type	string	The full Sui coin type for the output token.

---

BitFluxTask

Fetch the current swap price from a BitFlux pool.

Input: None

Returns: The swap price between the specified input and output tokens.

Example: Fetch the swap price using a custom RPC provider

{
  "bitFluxTask": {
    "provider": "https://my-custom-rpc.example.com",
    "poolAddress": "0x0000000000000000000000000000000000000000",
    "inToken": "0x0000000000000000000000000000000000000000",
    "outToken": "0x0000000000000000000000000000000000000000"
  }
}

Field	Type	Description
provider	string	Optional. The RPC endpoint to use for requests. If not specified, a default RPC will be used.
pool_address	string	The address of the BitFlux pool.
in_token	string	The address of the input token.
out_token	string	The address of the output token.

---

CorexTask

Fetch a swap quote from CoreX (Core chain) using Uniswap V3 pricing.

Input: Input token address, output token address, and slippage.

Returns: The quoted swap price for the requested pair.

Example: Quote STCORE -> WCORE

{
  "corexTask": {
    "inToken": "0xIN_TOKEN",
    "outToken": "0xOUT_TOKEN",
    "slippage": 0.01
  }
}

Field	Type	Description
in_token	string	The input token address.
out_token	string	The output token address.
slippage	double	The allowable slippage in percent for the swap quote.

---

EtherfuseTask

Fetch the current price for Etherfuse Stablebonds.

Input: The stablebond token to price.

Returns: The price of 1 bond in USDC.

Example: Fetch the CETES bond price

{
  "etherfuseTask": {
    "token": "TOKEN_CETES"
  }
}

Field	Type	Description
token	Token	The Etherfuse stablebond token to price.

---

FragmetricTask

Fetch the current price for Fragmetric liquid restaking tokens.

Input: None

Returns: The current price of the specified Fragmetric token relative to SOL (1.0 = 1 SOL)

Example: Fetch the fragSOL token price

{
  "fragmetricTask": {
    "token": "TOKEN_FRAG_SOL"
  }
}

Field	Type	Description
token	Token	The Fragmetric token to fetch the price for

---

GlyphTask

Fetch the spot price from a Glyph (Algebra) pool on Core.

Input: Pool address and swap direction.

Returns: The pool price in the requested direction.

Example: Token0 -> Token1 price

{
  "glyphTask": {
    "poolAddress": "0xPOOL_ADDRESS",
    "zeroForOne": true
  }
}

Field	Type	Description
pool_address	string	The Algebra pool address on Core.
zero_for_one	bool	True for token0 -> token1 price, false for token1 -> token0.

---

XStepPriceTask

Fetch the STEP/USD price either by running a MedianTask or reading an existing aggregator.

Input: Provide either step_job or step_aggregator_pubkey.

Returns: The STEP/USD price.

Example: Read from an existing STEP/USD aggregator

{
  "xstepPriceTask": {
    "stepAggregatorPubkey": "STEP_USD_AGGREGATOR"
  }
}

Field	Type	Description
step_job	MedianTask	median task containing the job definitions to fetch the STEP/USD price
step_aggregator_pubkey	string	existing aggregator pubkey for STEP/USD

---

Other

HistoryFunctionTask

Compute a reduction (min/max) over an aggregator's history buffer.

Input: Aggregator address, method, and lookback period (in seconds).

Returns: The min or max value observed in the period.

Example: Fetch the max price over the last hour

{
  "historyFunctionTask": {
    "aggregatorAddress": "AGGREGATOR_PUBKEY",
    "method": "METHOD_MAX",
    "period": 3600
  }
}

Field	Type	Description
method	Method	The reduction method to apply over the history buffer.
aggregator_address	string	The aggregator to query.
period	uint32	Lookback period in seconds.

---

LlmTask

Interacts with a Large Language Model (LLM) to generate a text response based on a user-provided prompt.

Input: None

Returns: Text generated by the LLM based on the provided prompt and configuration.

Example: Using OpenAI's GPT-4 model to generate a joke.

{
  "llmTask": {
    "providerConfig": {
      "openai": {
        "model": "gpt-4",
        "userPrompt": "Tell me a joke.",
        "temperature": 0.7,
        "secretNameApiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}

---

### MangoPerpMarketTask

Fetch the current price for a Mango perpetual market

| Field | Type | Description |
|-------|------|-------------|
| `perp_market_address` | string | Mainnet address for a mango perpetual market. A full list can be found here: https://github.com/blockworks-foundation/mango-client-v3/blob/main/src/ids.json |

---

### VwapTask

Compute a volume-weighted average price (VWAP) using price and volume aggregators.

_**Input**_: Price aggregator address, volume aggregator address, and lookback period (in seconds).

_**Returns**_: The VWAP over the specified period.

_**Example**_: Compute the 1h VWAP for a price/volume pair

```json
{
  "vwapTask": {
    "priceAggregatorAddress": "PRICE_AGGREGATOR",
    "volumeAggregatorAddress": "VOLUME_AGGREGATOR",
    "period": 3600
  }
}

Field	Type	Description
price_aggregator_address	string	The aggregator that provides price samples.
volume_aggregator_address	string	The aggregator that provides volume samples.
period	uint32	Lookback period in seconds.

---

Next Steps

• Build with TypeScript - Create feeds programmatically

• Build with UI - Use the visual feed builder

• Advanced Feed Configuration - Learn about variable overrides and more