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...

Security Scan

The skill is an instruction-only guide for interacting with a specific on-chain Kolect Sentiment Feed contract on Base and its requirements and instructions align with that purpose.

Purpose & Capability

The skill's name and description match the SKILL.md content: it documents read and write interactions with a specific on-chain sentiment oracle (contract address, explorer, network). It does not request unrelated resources or credentials.

Instruction Scope

SKILL.md stays on-topic: describes methods (getLatest, isFresh, hasPendingRequest, requestUpdate), event usage, validation rules, and example code (web3). It does not instruct reading arbitrary files, exfiltrating data, or contacting unknown endpoints. Note: requesting updates implies sending an on-chain transaction (gas + fee) and therefore requires a signer/wallet outside the skill; the skill does not attempt to manage or request private keys.

Install Mechanism

No install spec or code files are included; the README points to a GitHub repository/raw URL as an optional source for the SKILL.md, which is normal for documentation-only skills. There is no archive download or arbitrary executable install step.

Credentials

The skill declares no required environment variables, secrets, or config paths. The content uses a public RPC URL example and a public contract address; nothing in the files asks for unrelated credentials or tokens.

Persistence & Privilege

The skill is not marked always:true and has no install actions that grant it persistent system privileges. It is instruction-only and does not modify other skills or global agent settings.

Assessment

This skill is a documentation-only guide to interacting with the Kolect Sentiment Feed contract. Before using it: verify the contract address and repository source (the README points to a GitHub repo), and understand that initiating requestUpdate requires an on-chain transaction — you will need to sign and pay gas/fees with your wallet (the skill does not and should not ask for private keys). Do not paste private keys or secrets into the agent; if you plan to run the provided code, run it in a controlled environment and connect a wallet or signer you control. Finally, treat sentiment data as informational (not financial advice) and validate BPS invariants as the skill recommends.

---

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

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

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

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

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

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

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