Api3 Data Feed Purchase

Variables

Rules

• NEVER read .env files or ask for secrets such as WALLET_MNEMONIC.
• NEVER read, list, or search inside node_modules/, pnpm-lock.yaml, or pnpm-workspace.yaml,they are not needed for this skill nor relevant to the user.
• ALWAYS use the exec tool to run commands. Never use Bash or shell directly.
• ALWAYS run scripts from the skill's directory, referenced as {baseDir} (the directory named by the name field at the top of this file). 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 <CHAIN_ALIAS> and the feed/token symbol (e.g. the base of <DAPI_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
  • @openzeppelin/merkle-tree
  • 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 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 scripts/get-dapis.ts"
exec command="cd {baseDir} && ts-node scripts/get-chains.ts"

• If the script fails, let the 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: <DAPI_NAME>
  • Chain: <CHAIN_NAME>
  • Deviation Threshold: <DEVIATION>%
• 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 scripts/explore-data-feeds.ts <DAPI_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, Homepage, 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 scripts/quote.ts <CHAIN_ID> <DAPI_NAME> <DEVIATION>"

• If the script fails, let the 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 | |---|---| | dAPI | Feed | | Chain | Chain | | Deviation | Deviation Threshold | | Duration | Subscription Duration (seconds) | | Price | Subscription Price (ETH) | | Amount to send | Amount to Send (ETH) | | Sponsor wallet | Sponsor Wallet |

• If the amount to send is lower than the subscription price, explain that the sponsor wallet already holds funds, so only the difference needs to be sent.

• 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 to the 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 scripts/buy.ts <CHAIN_ID> <DAPI_NAME> <DEVIATION>"

• If the script fails with an Invalid root error, this means either Api3 Market (https://market.api3.org/) is closed due to ongoing integrations or skill is out of date and user should download the latest version of this skill.
• If the script fails for any other reason, let the user know about the problem and ask what to do.

Part 5.2

• Extract the transaction hash from the Confirmed: line of 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 the user if they want to read the data feed now. If yes, proceed. If no, inform the user that the subscription is active (though it's always better to verify the feed) and stop here.
• Ask the user to retrieve their Reader Proxy address by:
  • Going to https://market.api3.org/<CHAIN_ALIAS>/<DAPI_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 scripts/read-data-feed.ts <PROXY_ADDRESS> <CHAIN_ALIAS>"

• If the script fails, let the 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!