x402 Crypto Price Alerts

LinkLab Masterclass Book

The book is available at: https://smartcontractkit.github.io/x402-cre-price-alerts/

Overview

x402-cre is a demonstration project that showcases a complete crypto price alert system integrating three cutting-edge technologies:

• x402 Payment Protocol — Micropayment system for API access
• Chainlink CRE (Chainlink Runtime Environment) — Decentralized workflow execution for on-chain operations
• Gemini AI — Natural language processing for user interaction. While we used Gemini here you can use any LLM that has an OpenAI-API compatible endpoint.

This repository serves as a public demo to help developers understand how to build applications that combine AI-powered interfaces, payment-protected APIs, and blockchain-based automation.

LiveStreamed LinkLab Walkthrough

This demo was done live on a Chainlink Linklab Session that was livestreamed. You can watch the video and follow along here.

What It Accomplishes

The system allows users to create cryptocurrency price alerts through natural language conversation. Here's what happens:

1. User sends a message like "Alert me when BTC is greater than 60000"
2. AI interprets the request and extracts alert parameters (asset, condition, target price)
3. User pays $0.01 USDC via x402 payment protocol to create the alert
4. CRE workflow HTTP trigger — your x402 gateway server triggers your custom workflow using CRE's HTTP Capability
5. Alert is stored on-chain in a smart contract via Chainlink CRE's On-Chain Write Capability
6. CRE Cron Triggers monitor on-chain prices periodically using Chainlink Price Feeds
7. User receives push notification on phone when the price condition is met

This demonstrates a complete flow from user interaction → payment → blockchain storage → automated monitoring → notification delivery.

Minimal System Flow

Prerequisites

Before starting, ensure you have the following:

Required Software

• Node.js (v18 or higher) and npm
• Bun for the CRE post install script. Install here.
• Chainlink CRE CLI installed and configured. Install here.
• Git for cloning the repository

Required Accounts & Keys

• Gemini API Key: Get from Google AI Studio
• Pushover Account:
  • Sign up at pushover.net
  • Install Pushover app on your mobile device
  • Register your pushover app to get the API token and get your User Key from the Pushover dashboard
• Wallet with ETH and USDC on Base Sepolia:
  • Private key for the agent wallet (used for x402 payments)
  • Add Base Sepolia to your wallet (go here)
  • Get ETH on Base Sepolia testnet from this faucet for contract deployment
  • Get 1 USDC token on Base Sepolia testnet from this faucet for x402 payments (x402 facilitator covers gas fees)

Setup

1. Deploy RuleRegistry on Base Sepolia

Deploy contracts/RuleRegistry.sol to Base Sepolia. The constructor requires two parameters:

• USDC token address: 0x036CbD53842c5426634e7929541eC2318f3dCF7e (Base Sepolia USDC)
• Chainlink Forwarder address: 0x82300bd7c3958625581cc2f77bc6464dcecdf3e5 (Base Sepolia CRE Simulation Forwarder)

note Finding the Forwarder Address: Check the CRE documentation for the correct Chainlink Forwarder address for Base Sepolia testnet. The forwarder address is required to ensure only verified CRE reports can call the contract's onReport function.

You can use this Remix IDE link for this.

note Save the Contract Address: Note the deployed contract address, we will use this later.

2. Clone and install dependencies

git clone https://github.com/smartcontractkit/x402-cre-price-alerts.git
cd x402-cre-alerts

This repository uses npm workspaces. Install all dependencies with a single command:

npm install

This will install dependencies for both the server and cre/alerts workspaces. The cre/alerts post install script will automatically run bunx cre-setup.

3. Configure environment variables

Create a .env file in the project root (workspace root):

cp .env.example .env

note Workspace .env: The workspace setup uses a single .env file at the project root. Both server and cre workspaces can access environment variables from this root .env file. You may specify the .env file when using the CRE CLI by passing the --env argument.

Environment Variables Explained:

• PORT: Server port (default: 3000)
• X402_RECEIVER_ADDRESS: Address that receives x402 payments (Can be an EOA or Deployed RuleRegistry contract)
• X402_FACILITATOR_URL: x402 facilitator endpoint (default: https://x402.org/facilitator)
• GEMINI_API_KEY: Your Gemini API key for natural language processing
• AGENT_WALLET_PRIVATE_KEY: Private key of wallet used to make x402 payments (must have USDC on Base Sepolia). You can use the same key in step 4 as your CRE PK.

4. Configure CRE secrets

Add CRE-specific environment variables to the root .env file (same file as Step 3):

# Add these to your root .env file
# CRE_ETH_PRIVATE_KEY is used during local simulation when using the EVM Write capability.
# Transactions written will be signed by your PK. In production, a dedicated CRE DON will be the signer.
CRE_ETH_PRIVATE_KEY=your_eth_private_key
CRE_TARGET=staging-settings
PUSHOVER_USER_KEY_VAR=your_pushover_user_key
PUSHOVER_API_KEY_VAR=your_pushover_api_key

5. Configure CRE workflow

Edit cre/alerts/config.staging.json for staging/testing, or cre/alerts/config.production.json for production.

Update the config with your ruleRegistryAddress obtained in Step 1. If you were unable to deploy, you may use 0x9B9fC1EeF6BFC76CD07501Ae81b66f24fAB322B1 (note: this demo contract may be populated with multiple alerts from other developers).

{
  "schedule": "0 0 * * * *",
  "ruleTTL": 1800,
  "publicKey": "",
  "evms": [
    {
      "ruleRegistryAddress": "your_deployed_rule_registry",
      "chainSelectorName": "ethereum-testnet-sepolia-base-1",
      "gasLimit": "1000000",
      "dataFeeds": {
        "BTC": "0x0FB99723Aee6f420beAD13e6bBB79b7E6F034298",
        "ETH": "0x4aDC67696bA383F43DD60A9e78F2C97Fbbfc7cb1",
        "LINK": "0xb113F5A928BCfF189C998ab20d753a47F9dE5A61"
      }
    }
  ]
}

Configuration Fields:

• schedule: Cron expression for price checks (default: hourly - "0 0 * * * *")
• ruleTTL: Time to live of a created rule (30 minutes by default. Older rules will not receive alerts.)
• publicKey: Public key used to verify incoming HTTP Trigger requests. This field is empty for this demo. However, it is required when the full HTTP Trigger is implemented for production. See Line 64 of server/src/server.ts
• ruleRegistryAddress: Address of your deployed RuleRegistry contract
• chainSelectorName: Chain selector for Base Sepolia ("ethereum-testnet-sepolia-base-1"). See the chain selector reference
• gasLimit: Gas limit for on-chain writes
• dataFeeds: Chainlink price feed addresses for BTC, ETH, LINK on Base Sepolia. You can find Base Sepolia Price Feed addresses here.

Environment Variables Explained:

• CRE_ETH_PRIVATE_KEY: ETH private key used for local simulation of EVM Write capability
• CRE_TARGET: Target profile for CLI commands
• PUSHOVER_USER_KEY_VAR: Your Pushover user key
• PUSHOVER_API_KEY_VAR: Your Pushover API key

Execution

1. Start the server

From the repository root, run the server:

npm run dev:server

The server will start on http://localhost:3000 (or your configured PORT).

You should see the Unified API Server banner with Port, Payment, POST /chat and POST /alerts endpoints, and Interactive Chat Enabled.

2. Create an alert via natural language

You can interact with the chat interface in two ways:

Option A: Interactive Chat (Recommended)

Send a message to create your alert:

> Create an alert when BTC is greater than 60000

note Testing Tip: This is deliberately set to below current market price so that the trigger fires.

Type exit or quit to disable chat (server continues running).

Option B: Direct API Call

Alternatively, send a POST request to the /chat endpoint:

curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Create an alert when BTC is greater than 60000"}'

What happens: Gemini AI interprets your message; extracts alert parameters (asset, condition, target price); creates a paid alert via /alerts endpoint with x402 payment; returns alert details and payment transaction hash.

Supported Assets: BTC, ETH, LINK only

3. Copy alert JSON payload

From the server console output, copy the CRE payload JSON. Example: {"id":"...","asset":"ETH","condition":"gt","targetPriceUsd":1000,"createdAt":1765324585}

4. Write alert to chain (CRE HTTP Trigger)

Open a new terminal window and simulate the CRE HTTP Trigger to write the alert on-chain:

cd cre
cre workflow simulate alerts --env ../.env --broadcast

When prompted: Select HTTP trigger (option 2); paste the JSON payload from Step 3. The workflow will write the alert to the RuleRegistry contract on-chain.

5. Check price conditions (CRE Cron Trigger)

Execute the CRE Cron Trigger to check prices and send notifications:

cre workflow simulate alerts --env ../.env

When prompted: Select Cron trigger (option 1). The workflow will fetch current prices for BTC, ETH, LINK; check all rules stored on-chain; send Pushover notifications when conditions are met.

note Automatic Scheduling: The cron trigger runs automatically on the configured schedule once deployed. The frequency of the CRON trigger is set within cre/alerts/config.staging.json, as well as the Rule TTL.

6. Review the Pushover notification on your device

7. (Optional) View balance and withdraw funds

• View balance of x402 Receiver: If you set your x402 Receiver in the root .env file (X402_RECEIVER_ADDRESS) to your RuleRegistry contract, call getUSDCBalance() to see the USDC received from x402 payments.
• Withdraw USDC tokens from RuleRegistry: If you set your x402 Receiver to your RuleRegistry contract, call withdrawUSDC(address, amount) to withdraw USDC received from x402 payments. Reminder, USDC uses 6 decimal places!

Directory Structure

server/ — Purpose: Unified API server combining natural language interface and payment-protected endpoints.

Key Components: src/server.ts (POST /chat, POST /alerts), src/x402Client.ts (x402 payment client), src/chat.ts (interactive terminal chat). Technologies: Express.js, x402-express middleware, Gemini AI (OpenAI SDK compatibility).

cre/ — Purpose: Chainlink CRE workflow for on-chain operations and price monitoring.

Key Components: alerts/main.ts (HTTP and Cron triggers), alerts/httpCallback.ts (HTTP trigger, encode and write to RuleRegistry), alerts/cronCallback.ts (Cron trigger, fetch prices, read rules, send Pushover), alerts/config.staging.json, alerts/config.production.json, alerts/workflow.yaml, alerts/types.ts, project.yaml, secrets.yaml. Technologies: Chainlink CRE SDK, Viem, Chainlink Price Feeds, Pushover API.

contracts/ — Purpose: Solidity smart contracts for on-chain alert storage.

Key Components: RuleRegistry.sol (stores rules, IReceiverTemplate, onlyOwner withdraw). Rule struct: id, asset, condition, targetPriceUsd, createdAt. interfaces/: IReceiverTemplate.sol, IReceiver.sol, IERC165.sol, IERC20.sol. Technologies: Solidity ^0.8.0, Chainlink CRE receiver interfaces.

General Flow

1. Alert Creation Flow: User → /chat → Gemini AI → Extract Parameters → /alerts → x402 Payment → Alert Created
2. On-Chain Storage Flow: Server Output → CRE HTTP Trigger → Encode Report → Write to RuleRegistry Contract
3. Price Monitoring Flow: Cron Schedule → CRE Cron Trigger → Fetch Prices → Read Rules → Check Conditions → Send Notifications
4. x402 Payment Flow: Client Request → 402 Challenge → Payment Authorization → Settlement → Response

Key Technologies Integration

• x402 Payment Protocol: Micropayments for API access. x402-express + x402-fetch. $0.01 USDC on Base Sepolia. Flow: Challenge → Authorization → Settlement.
• Chainlink CRE: Decentralized workflow execution. CRE SDK with HTTP and Cron triggers. EVM contract calls, price feed queries. Base Sepolia testnet.
• Gemini AI: Natural language understanding. OpenAI SDK compatibility. Model: gemini-2.0-flash-lite. Function calling for structured extraction.
• Chainlink Price Feeds: BTC, ETH, LINK on Base Sepolia. 8 decimals.

Supported Features

• Assets: BTC, ETH, LINK only
• Conditions: gt, lt, gte, lte
• Notifications: Pushover push notifications to mobile devices
• Payment: $0.01 USDC per alert creation
• Storage: On-chain in RuleRegistry smart contract
• Monitoring: Automated hourly price checks