Api3 Data Feed Purchase

Variables

Rules

• NEVER read .env files or ask for secrets such as WALLET_MNEMONIC.
• ALWAYS use the exec tool to run commands. Never use Bash or shell directly.
• ALWAYS run scripts in skill's directory, which is referenced as {baseDir} variable and name is given in this file's name field at top. Prefix every command with cd {baseDir} && to ensure it runs from the correct directory.
• ALWAYS substitute actual variable values into every exec command before running it.
• ALWAYS after asking any question, stop and wait for the user's response. Do not assume a response or continue until the user has replied.
• ALWAYS complete the current phase fully before moving to the next. Never skip a phase or assume it is already done.
• Treat affirmative responses as approval (e.g. "yes", "sure", "ok", "go ahead", "yep"). Treat negative responses as rejection (e.g. "no", "nope", "cancel", "stop"). If intent is unclear, ask once more before acting.
• NEVER wrap URLs in markdown formatting (backticks, asterisks, brackets, etc.) or add trailing punctuation when sharing them with the user — share the raw URL as plain text so it stays clickable and isn't corrupted with extra characters.
• ALWAYS lowercase \x3CCHAIN_ALIAS> and the feed/token symbol (e.g. the base of \x3CDAPI_NAME>) when substituting them into market.api3.org URL paths (e.g. https://market.api3.org/ethereum/eth-usd/integrate), even if the confirmed values are stored/displayed with different casing.

Phase 0: Introduction

• Introduce the skill: you will walk the user through purchasing an Api3 data feed subscription on-chain, step by step. You will ask for approval before installing packages and before executing the purchase transaction.
• Ask if they are ready to begin and wait for an affirmative response before continuing.

Phase 1: Package Installation

Part 1.1

• You must always run this step. Do not skip it, even if you think packages are already installed.
• Inform the user that before any scripts can run, the required packages must be installed. Show them the list:
  • @api3/dapi-management
  • dotenv
  • ethers
• Ask for approval to run pnpm install. Wait for an affirmative response. Once approved, run the command regardless of whether packages may already be installed:

exec command="cd {baseDir} && pnpm install"

• If the output contains [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: unrs-resolver..., this is expected and not a real failure — the ignored build script is not needed for this skill. Treat it as success and continue.
• If the command fails for any other reason, inform the user and ask what to do. This step cannot be skipped.

Phase 2: Collect User Input

Part 2.1

• Ask the user for all three inputs in one message:
  • Feed name — which data feed they want (e.g. ETH/USD). Direct them to https://market.api3.org to browse available feeds.
  • Chain — which network they want to use (name or alias, e.g. ethereum).
  • Deviation threshold — must be exactly one of: 0.25, 0.5, 1, 2.5, 5 (percent).
• Wait for all three answers before continuing.

Part 2.2

• Run get-dapis.ts and get-chains.ts to fetch the list of available feeds and supported chains:

exec command="cd {baseDir} && ts-node {baseDir}/scripts/get-dapis.ts"
exec command="cd {baseDir} && ts-node {baseDir}/scripts/get-chains.ts"

• If script fails, let user know about the problem and ask what to do. This data is necessary for validating their input, so skipping is not an option.

Part 2.3

• Validate DAPI_NAME:

  • Search the output of get-dapis.ts for an entry matching the user's feed name exactly (case-insensitive).
  • Match found: set DAPI_NAME to the exact string from the list (preserve its casing) and confirm the matched value to the user.
  • No match: inform the user, direct them to https://market.api3.org for the exact feed name, and wait for a new value. Repeat this step.

• Validate CHAIN_ALIAS:

  • Search the output of get-chains.ts — first by alias field (case-insensitive), then by name field.
  • Match found: set CHAIN_ALIAS, CHAIN_NAME, CHAIN_ID from that entry. Confirm the match with the user and ask if it is correct. If not, ask them to re-enter and repeat this step.
  • No match: inform the user, direct them to https://market.api3.org for supported chains, and wait for a new value. Repeat this step.

• Validate DEVIATION:

  • Check that the value is exactly one of: 0.25, 0.5, 1, 2.5, 5.
  • Valid: set DEVIATION.
  • Invalid: inform the user of the valid options and wait for a new answer. Repeat this step.

Part 2.4

• Show the user a summary of their selected options:
  • Feed: \x3CDAPI_NAME>
  • Chain: \x3CCHAIN_NAME>
  • Deviation Threshold: \x3CDEVIATION>%
• Ask the user to confirm that they want to proceed with these options. If no, ask the user what they want to do.
• If yes, ask whether they'd also like to explore the data feed first — i.e. see the live value each data provider is currently reporting for this feed before getting a price quote. If yes, proceed to Phase 3. If no, skip ahead to Phase 4.

Phase 3: Check Live Provider Values (Optional)

Part 3.1

• Explain to the user that before continuing, you'll show them the live value each data provider is currently reporting for this feed, so they can sanity-check the data before paying for it.
• Run explore-data-feeds.ts, which fetches each provider's Signed API data and decodes the live value for this feed directly:

exec command="cd {baseDir} && ts-node {baseDir}/scripts/explore-data-feeds.ts \x3CDAPI_NAME>"

• If the script fails, let the user know about the problem and ask what to do.

Part 3.2

• The script prints, for each provider: API Alias, Data Feed ID, Signed API URL, Value, and Timestamp (or an explanation if no value could be retrieved).
• Show the user a summary table of these fields for each provider exactly as reported by the script — do not re-fetch or re-derive any of these values yourself.
• Proceed to Phase 4.

Phase 4: Get Price Quote

Part 4.1

• Run quote.ts to fetch the live subscription price for the selected feed, chain, and deviation:

exec command="cd {baseDir} && ts-node {baseDir}/scripts/quote.ts \x3CDAPI_NAME> \x3CCHAIN_ALIAS> \x3CDEVIATION>"

• If script fails, let user know about the problem and ask what to do.

Part 4.2

• Extract and show these fields from the output:

  Field	Label to show
  Feed Name	Feed
  Chain	Chain
  Heartbeat Interval	Heartbeat Interval (seconds)
  Deviation Threshold	Deviation Threshold
  Subscription Duration	Subscription Duration (seconds)
  Price (ETH)	Price (ETH)

• Ask the user to confirm that they want to proceed with these options. If yes, proceed to Phase 5. If no, ask the user what they want to do.

Phase 5: Execute Purchase

Part 5.1

• Explain user that you are ready to complete the purchase. You will run buy.ts, which will execute a blockchain transaction to purchase the subscription.
• Explain this script will use the WALLET_MNEMONIC environment variable to sign the transaction. Make sure the user has WALLET_MNEMONIC set in .env file in the root of this skill.
• Ask if the .env file is ready with the correct mnemonic and if they want you to run the purchase script. Wait for an affirmative response before proceeding. Then run the following command if answer is affirmative:

(substitute actual variable values when running):

exec command="cd {baseDir} && ts-node {baseDir}/scripts/buy.ts \x3CDAPI_NAME> \x3CCHAIN_ALIAS> \x3CDEVIATION>"

• If script fails, let user know about the problem and ask what to do.

Part 5.2

• Extract the hash value from the output and show the purchase summary: feed, chain, deviation, subscription duration, and transaction hash.
• Proceed to Phase 6.

Phase 6: Read the Data Feed

Part 6.1

• Ask user if they want to read the data feed now. If yes, proceed. If no, inform the user the subscription is active, but its always better to check and stop.
• Ask the user to retrieve their Reader Proxy address by:
  • Going to https://market.api3.org/\x3CCHAIN_ALIAS>/\x3CDAPI_NAME lowercased, with / replaced by ->/integrate
  • Copying the proxy contract address and sharing it here.
• Wait for the user to provide the proxy address.
• Validate the proxy address:
  • Must start with 0x.
  • Must be exactly 42 characters long.
  • If either check fails: inform the user of the requirements and wait again.
• Set PROXY_ADDRESS to the valid value.

Part 6.2

• Run read-data-feed.ts to fetch the latest value and timestamp from the proxy contract:

exec command="cd {baseDir} && ts-node {baseDir}/scripts/read-data-feed.ts \x3CPROXY_ADDRESS> \x3CCHAIN_ALIAS>"

• If script fails, let user know about the problem and ask what to do.
• Extract and show the value and timestamp from the output.
• Inform the user the feed is active and readable and congratulate them on successfully purchasing an Api3 data feed subscription!