Kolect Sentiment

Query, check freshness, check pending requests, or request new sentiment updates on-chain for supported symbols and time windows via the Kolect Sentiment Fee...

Kolect-info@kolect-info

Install

openclaw skills install @kolect-info/kolect-sentiment

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:

User requests an update on-chain
Off-chain publisher fetches sentiment from Kolect API
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

Identify symbol and timeWindow
Use getLatest(symbol, timeWindow)
Present:
- negative / neutral / positive
- both BPS and %
- dataTimestamp
- updatedAt

If the user asks whether an update is needed

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

If the user wants to request an update

Identify symbol and timeWindow
Check:
- supported symbol
- supported time window
- not fresh
- no pending request
- fee requirement
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:

negativeBps + neutralBps + positiveBps == 10000
each value is non-negative
dataTimestamp = off-chain data time
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:

getLatest(symbol, timeWindow)
validate BPS values
isFresh(symbol, timeWindow)
hasPendingRequest(symbol, timeWindow)
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