---

name: kolect-sentiment-feed description: Use this skill when the user wants to read, explain, or interact with the Kolect Sentiment Feed contract on Base, including querying sentiment, checking freshness, checking pending requests, and requesting new on-chain sentiment updates for supported symbols and time windows.#

Kolect Sentiment Feed#

Purpose#

Use this skill for the Kolect Sentiment Feed contract, an on-chain sentiment oracle on Base.

It stores normalized sentiment for supported (symbol, timeWindow) pairs through a request–response flow:

1. User requests an update on-chain
2. Off-chain publisher fetches sentiment from Kolect API
3. Publisher fulfills the request on-chain with normalized BPS data

Use this skill when the user wants to:

• read the latest sentiment
• check freshness
• check pending request state
• request a new update
• understand how the oracle works
• integrate the feed into AI agents, trading, dashboards, or DeFi logic

---

Contract#

• Project: Kolect
• Module: Kolect Sentiment Feed
• Version: v1.0.0
• Network: Base
• Address: 0x6783ab3c181976e8c960c43d711aaf4da79a4e4b
• Explorer: https://base.blockscout.com/address/0x6783ab3c181976e8c960c43d711aaf4da79a4e4b
• Website: https://kolect.info
• Twitter/X: https://x.com/kolect_info

---

Interaction Types#

Read-only calls#

Usually used to inspect current state:

• getLatest(symbol, timeWindow)
• isFresh(symbol, timeWindow)
• hasPendingRequest(symbol, timeWindow)

These are normally read calls and do not require the contract request fee.

Write call#

Used to initiate a new oracle update:

• requestUpdate(symbol, timeWindow)

This is not a free read. It is a state-changing transaction:

• requires gas
• may require request fee payment

Never present requestUpdate as a free data read.

---

Data Model#

Each feed is identified by:

• symbol
• timeWindow

Examples:

• (BTC, 1d)
• (ETH, 1h)

Each feed stores:

• negativeBps
• neutralBps
• positiveBps
• dataTimestamp — off-chain data time
• updatedAt — on-chain fulfillment time

Invariant#

negativeBps + neutralBps + positiveBps = 10000

Interpretation:

• 10000 = 100.00%
• 2500 = 25.00%
• 5000 = 50.00%

Always preserve and validate this rule.

---

Core Workflow#

1. Request update#

Function: requestUpdate(string symbol, string timeWindow)

Should only succeed if:

• symbol is supported
• time window is supported
• feed is not already fresh
• no pending request exists
• required fee is paid

2. Off-chain processing#

Publisher:

• listens to UpdateRequested
• fetches sentiment from Kolect API
• normalizes result into BPS

3. Fulfillment#

Function: fulfillRequest(requestId, negativeBps, neutralBps, positiveBps, dataTimestamp)

Result:

• data stored on-chain
• request marked fulfilled
• event emitted

4. Failure#

Function: failRequest(requestId, errorCode)

Used when data retrieval or fulfillment fails.

---

Functions#

User#

• requestUpdate(string symbol, string timeWindow)

View#

• getLatest(symbol, timeWindow)
• isFresh(symbol, timeWindow)
• hasPendingRequest(symbol, timeWindow)

Publisher#

• fulfillRequest(...)
• failRequest(...)

Owner#

• setSupportedSymbol(...)
• setSupportedTimeWindow(...)
• setUpdateInterval(...)
• setRequestFee(...)
• withdrawFees(...)

Do not imply ordinary users can call owner-only functions.

---

Events#

Important indexing events:

• UpdateRequested
• RequestFulfilled
• RequestFailed

Use these when discussing dashboards, Dune, subgraphs, analytics, or automation.

---

Decision Logic#

If the user wants the latest sentiment#

1. Identify symbol and timeWindow
2. Use getLatest(symbol, timeWindow)
3. Present:
   • negative / neutral / positive
   • both BPS and %
   • dataTimestamp
   • updatedAt

If the user asks whether an update is needed#

1. Check isFresh(symbol, timeWindow)
2. If fresh, explain no update may be needed
3. If stale, explain requestUpdate may be appropriate

If the user wants to request an update#

1. Identify symbol and timeWindow
2. Check:
   • supported symbol
   • supported time window
   • not fresh
   • no pending request
   • fee requirement
3. Then prepare or describe requestUpdate(symbol, timeWindow)

If the user asks why a request may fail#

Likely reasons:

• unsupported symbol
• unsupported time window
• feed already fresh
• request already pending
• fee missing
• publisher fulfillment failure

---

Output Format#

When reporting sentiment, use:

• Symbol: BTC
• Time window: 1d
• Negative: 2300 BPS (23.00%)
• Neutral: 4100 BPS (41.00%)
• Positive: 3600 BPS (36.00%)
• Data timestamp: [off-chain time]
• Updated on-chain at: [on-chain time]
• Fresh: [true/false if known]
• Pending request: [true/false if known]

Do not report only raw integers unless explicitly requested.

---

Validation Rules#

Whenever sentiment data is given, validate:

1. negativeBps + neutralBps + positiveBps == 10000
2. each value is non-negative
3. dataTimestamp = off-chain data time
4. updatedAt = on-chain update time

If the sum is not 10000, flag it as invalid.

---

Python Examples#

Read latest sentiment#

python

from web3 import Web3

RPC_URL = "https://mainnet.base.org"
CONTRACT_ADDRESS = Web3.to_checksum_address("0x6783ab3c181976e8c960c43d711aaf4da79a4e4b")

ABI = [
    {
        "inputs": [
            {"internalType": "string", "name": "symbol", "type": "string"},
            {"internalType": "string", "name": "timeWindow", "type": "string"}
        ],
        "name": "getLatest",
        "outputs": [
            {"internalType": "uint256", "name": "negativeBps", "type": "uint256"},
            {"internalType": "uint256", "name": "neutralBps", "type": "uint256"},
            {"internalType": "uint256", "name": "positiveBps", "type": "uint256"},
            {"internalType": "uint256", "name": "dataTimestamp", "type": "uint256"},
            {"internalType": "uint256", "name": "updatedAt", "type": "uint256"}
        ],
        "stateMutability": "view",
        "type": "function"
    }
]

w3 = Web3(Web3.HTTPProvider(RPC_URL))
contract = w3.eth.contract(address=CONTRACT_ADDRESS, abi=ABI)

symbol = "BTC"
time_window = "1d"

negative_bps, neutral_bps, positive_bps, data_timestamp, updated_at = (
    contract.functions.getLatest(symbol, time_window).call()
)

print("Negative:", negative_bps, f"({negative_bps / 100:.2f}%)")
print("Neutral:", neutral_bps, f"({neutral_bps / 100:.2f}%)")
print("Positive:", positive_bps, f"({positive_bps / 100:.2f}%)")
print("Data timestamp:", data_timestamp)
print("Updated at:", updated_at)

Check freshness and pending request#

python

from web3 import Web3

RPC_URL = "https://mainnet.base.org"
CONTRACT_ADDRESS = Web3.to_checksum_address("0x6783ab3c181976e8c960c43d711aaf4da79a4e4b")

ABI = [
    {
        "inputs": [
            {"internalType": "string", "name": "symbol", "type": "string"},
            {"internalType": "string", "name": "timeWindow", "type": "string"}
        ],
        "name": "isFresh",
        "outputs": [{"internalType": "bool", "name": "", "type": "bool"}],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [
            {"internalType": "string", "name": "symbol", "type": "string"},
            {"internalType": "string", "name": "timeWindow", "type": "string"}
        ],
        "name": "hasPendingRequest",
        "outputs": [{"internalType": "bool", "name": "", "type": "bool"}],
        "stateMutability": "view",
        "type": "function"
    }
]

w3 = Web3(Web3.HTTPProvider(RPC_URL))
contract = w3.eth.contract(address=CONTRACT_ADDRESS, abi=ABI)

symbol = "ETH"
time_window = "1h"

fresh = contract.functions.isFresh(symbol, time_window).call()
pending = contract.functions.hasPendingRequest(symbol, time_window).call()

print("Fresh:", fresh)
print("Pending:", pending)

Request an update#

python

from web3 import Web3

RPC_URL = "https://mainnet.base.org"
PRIVATE_KEY = "YOUR_PRIVATE_KEY"
ACCOUNT = "YOUR_WALLET_ADDRESS"
CONTRACT_ADDRESS = Web3.to_checksum_address("0x6783ab3c181976e8c960c43d711aaf4da79a4e4b")

ABI = [
    {
        "inputs": [
            {"internalType": "string", "name": "symbol", "type": "string"},
            {"internalType": "string", "name": "timeWindow", "type": "string"}
        ],
        "name": "requestUpdate",
        "outputs": [],
        "stateMutability": "payable",
        "type": "function"
    }
]

w3 = Web3(Web3.HTTPProvider(RPC_URL))
contract = w3.eth.contract(address=CONTRACT_ADDRESS, abi=ABI)

symbol = "BTC"
time_window = "1d"
request_fee_wei = 0  # replace with actual fee if needed

tx = contract.functions.requestUpdate(symbol, time_window).build_transaction({
    "from": ACCOUNT,
    "nonce": w3.eth.get_transaction_count(ACCOUNT),
    "value": request_fee_wei,
    "gas": 300000,
    "gasPrice": w3.eth.gas_price,
    "chainId": 8453
})

signed_tx = w3.eth.account.sign_transaction(tx, PRIVATE_KEY)
tx_hash = w3.eth.send_raw_transaction(signed_tx.raw_transaction)
print(tx_hash.hex())

---

JavaScript Examples#

Read latest sentiment#

javascript

import { ethers } from "ethers";

const RPC_URL = "https://mainnet.base.org";
const CONTRACT_ADDRESS = "0x6783ab3c181976e8c960c43d711aaf4da79a4e4b";

const ABI = [
  "function getLatest(string symbol, string timeWindow) view returns (uint256 negativeBps, uint256 neutralBps, uint256 positiveBps, uint256 dataTimestamp, uint256 updatedAt)"
];

const provider = new ethers.JsonRpcProvider(RPC_URL);
const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

const result = await contract.getLatest("BTC", "1d");

console.log(Number(result.negativeBps), Number(result.neutralBps), Number(result.positiveBps));
console.log(Number(result.dataTimestamp), Number(result.updatedAt));

Check freshness and pending request#

javascript

import { ethers } from "ethers";

const RPC_URL = "https://mainnet.base.org";
const CONTRACT_ADDRESS = "0x6783ab3c181976e8c960c43d711aaf4da79a4e4b";

const ABI = [
  "function isFresh(string symbol, string timeWindow) view returns (bool)",
  "function hasPendingRequest(string symbol, string timeWindow) view returns (bool)"
];

const provider = new ethers.JsonRpcProvider(RPC_URL);
const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

const fresh = await contract.isFresh("ETH", "1h");
const pending = await contract.hasPendingRequest("ETH", "1h");

console.log("Fresh:", fresh);
console.log("Pending:", pending);

Request an update#

javascript

import { ethers } from "ethers";

const RPC_URL = "https://mainnet.base.org";
const PRIVATE_KEY = "YOUR_PRIVATE_KEY";
const CONTRACT_ADDRESS = "0x6783ab3c181976e8c960c43d711aaf4da79a4e4b";

const ABI = [
  "function requestUpdate(string symbol, string timeWindow) payable"
];

const provider = new ethers.JsonRpcProvider(RPC_URL);
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, wallet);

const tx = await contract.requestUpdate("BTC", "1d", {
  value: 0n // replace with actual request fee if needed
});

console.log(tx.hash);
await tx.wait();

---

Recommended Agent Behavior#

An AI agent should use the feed in this order:

1. getLatest(symbol, timeWindow)

2. validate BPS values

3. isFresh(symbol, timeWindow)

4. hasPendingRequest(symbol, timeWindow)

5. only if stale and no pending request exists:

   • prepare or send requestUpdate(symbol, timeWindow)

Recommended phrasing:

The Kolect Sentiment Feed lets the agent consume verifiable on-chain sentiment state. The agent should first read current state, then verify freshness, and only request a new update when needed.

---

Action Policy#

• If the user asks for explanation only, explain the contract and do not push a write transaction.
• If the user asks for current sentiment, prefer read calls first.
• If the user asks to refresh, explain freshness and pending checks before suggesting requestUpdate.
• Never suggest owner-only functions unless the user is explicitly admin/operator.
• Never imply all interactions are free. Read calls are usually free from the contract side; write calls need gas and may need request fee.

---

Safe Assumptions#

The model may assume:

• this contract is on Base
• the address above is the intended deployment
• sentiment is normalized in BPS

The model must not assume without checking:

• supported symbols
• supported time windows
• current request fee
• current update interval
• whether a feed is fresh right now
• whether a request is pending right now

These are dynamic contract states.

---

Anti-Patterns#

Do not:

• confuse BPS with percentages
• say the contract computes sentiment internally
• describe the feed as auto-updating on a timer
• assume request fee is zero
• merge dataTimestamp and updatedAt
• assume all symbols and time windows are supported by default
• tell the user to call requestUpdate before checking freshness and pending state

---

Minimal Cheat Sheet#

Chain: Base Contract: 0x6783ab3c181976e8c960c43d711aaf4da79a4e4b

Main user action

• requestUpdate(symbol, timeWindow)

Main read functions

• getLatest(symbol, timeWindow)
• isFresh(symbol, timeWindow)
• hasPendingRequest(symbol, timeWindow)

Publisher functions

• fulfillRequest(...)
• failRequest(...)

Key events

• UpdateRequested
• RequestFulfilled
• RequestFailed

Core invariant

• negativeBps + neutralBps + positiveBps = 10000