Developer guide · miner SDK
Orenya Commerce Agent
Open TypeScript SDK to run the flagship Amazon miner or deploy your own agent on the Orenya network. LLM intent parsing, catalog search, deterministic scoring, and transparent SSE traces — the same pipeline validators will attest.
Introduction
Orenya is an open agent stack for AI commerce miners — not a closed platform catalog. Operators connect a product search API (Amazon, Shopify, custom), run inference through the SDK, and stream step-by-step session traces for network rewards. You can also embed the widget on any storefront.
Division of responsibility
| Your marketplace provides | Commerce Agent handles |
|---|---|
searchProducts(query) — product retrieval | User intent analysis (LLM) |
| Catalog data (IDs, titles, prices, images) | Product scoring vs. shopper intent |
| Checkout, inventory, fulfillment | Personalization and constraint matching |
| Your brand, theme, and UX | Recommendation generation (best matches + more picks) |
Reduced integration complexity
You do not need to build LLM pipelines, scoring heuristics, or recommendation logic. Implement two catalog endpoints (or reuse existing ones), configure the SDK, and embed the widget.
Packages
| Package | Role |
|---|---|
@commerce-agent/core | Intent parsing, scoring, agent orchestration |
@commerce-agent/server | REST + SSE API for your backend |
@commerce-agent/widget | Embeddable, themeable chat UI for any storefront |
Integration model
The agent calls your catalog through a thin HTTP contract. If you already expose product search internally, map it to these routes:
| Endpoint | Purpose |
|---|---|
GET /search/find_product | Search — equivalent to searchProducts(query) |
GET /search/view_product_information | Product details for scoring (attributes, descriptions) |
// Your marketplace already has product search.
// Expose it behind two HTTP endpoints the agent calls:
// GET /search/find_product?q=wireless+earbuds&page=1&price=0-50
// → Product[]
// GET /search/view_product_information?product_ids=SKU1,SKU2
// → { product_id, title, description, attributes }[]
// Conceptually:
async function searchProducts(query: string): Promise<Product[]> {
return catalogClient.findProduct({ q: query, page: 1 });
}interface Product {
product_id: string; // required — your SKU / ASIN / listing ID
title?: string;
price?: number; // USD or your marketplace currency
image?: string;
shop_id?: string;
brand?: string;
service?: string[]; // e.g. prime, freeShipping
}Getting started
Install the SDK, connect your catalog API, and embed the widget on your marketplace. The live demo on this site uses Rainforest API as a sample catalog for testing only — replace it with your own search backend in production.
Installation
Requires Node.js 18+ and npm.
npm install commerce-agent-jsQuick start
Connect your marketplace catalog and LLM key:
import { createCommerceAgentRouter } from "@commerce-agent/server";
createCommerceAgentRouter({
agentConfig: {
useLocalAgent: true,
productApi: {
baseUrl: process.env.MARKETPLACE_CATALOG_URL, // your search API
apiKey: process.env.MARKETPLACE_API_KEY, // optional
},
llm: {
baseUrl: process.env.LLM_BASE_URL,
apiKey: process.env.LLM_API_KEY,
model: "gpt-4o-mini",
},
},
corsOrigins: ["https://your-marketplace.com"],
}).mount(app);<!-- Orenya-hosted widget (or self-host commerce-agent-widget.js) -->
<script src="https://orenya.io/widget/commerce-agent-widget.js"></script>
<script>
CommerceAgentWidget.init({
apiUrl: "https://orenya.io/api/agent",
delegateProductApi: false,
theme: {
mode: "dark", // or "light" | "auto" (follows data-theme / system)
primaryColor: "#ff9138",
position: "bottom-right",
},
title: "Shopping Assistant",
greeting: "What are you looking for? I'll find the best matches.",
placeholder: "e.g. wireless earbuds under $50",
onProductClick: (product) => {
window.location.href = "/product/" + product.product_id;
},
});
</script>Packages
Core SDK
Use runCommerceAgent programmatically with your CatalogApiClient or a custom ProductApiPort.
import { CommerceAgent, CatalogApiClient, runCommerceAgent } from "@commerce-agent/core";
// Plug in your marketplace catalog
const catalog = new CatalogApiClient({
baseUrl: "https://api.your-marketplace.com",
apiKey: process.env.MARKETPLACE_API_KEY,
});
const result = await runCommerceAgent(
"Find waterproof running shoes under $100, Nike preferred",
catalog,
{
llm: {
baseUrl: process.env.LLM_BASE_URL!,
apiKey: process.env.LLM_API_KEY!,
},
},
);
// Agent output — you render these in your UI
console.log(result.bestMatches); // top picks after scoring
console.log(result.recommendations); // additional matchesServer
Mount createCommerceAgentRouter on Express (or use the built-in Next.js routes in this repo's website/ demo). The server holds your LLM key — never expose it in the browser.
import { createCommerceAgentRouter } from "@commerce-agent/server";
createCommerceAgentRouter({
agentConfig: {
useLocalAgent: true,
productApi: {
baseUrl: process.env.MARKETPLACE_CATALOG_URL, // your search API
apiKey: process.env.MARKETPLACE_API_KEY, // optional
},
llm: {
baseUrl: process.env.LLM_BASE_URL,
apiKey: process.env.LLM_API_KEY,
model: "gpt-4o-mini",
},
},
corsOrigins: ["https://your-marketplace.com"],
}).mount(app);Widget
The widget is fully customizable: theme colors, position, greeting, placeholder, title, and onProductClick. Each marketplace ships its own branded assistant while sharing the same agent core.
<!-- Orenya-hosted widget (or self-host commerce-agent-widget.js) -->
<script src="https://orenya.io/widget/commerce-agent-widget.js"></script>
<script>
CommerceAgentWidget.init({
apiUrl: "https://orenya.io/api/agent",
delegateProductApi: false,
theme: {
mode: "dark", // or "light" | "auto" (follows data-theme / system)
primaryColor: "#ff9138",
position: "bottom-right",
},
title: "Shopping Assistant",
greeting: "What are you looking for? I'll find the best matches.",
placeholder: "e.g. wireless earbuds under $50",
onProductClick: (product) => {
window.location.href = "/product/" + product.product_id;
},
});
</script>Browser-delegated search (optional)
If you prefer the browser to call your catalog API directly (agent logic still runs server-side), enable delegation:
// Alternative: browser calls YOUR search API directly
CommerceAgentWidget.init({
apiUrl: "https://api.your-marketplace.com/api/agent",
delegateProductApi: true,
productApi: {
baseUrl: "https://api.your-marketplace.com",
apiKey: "optional-bearer-token",
},
});Agent API reference
Routes mounted under /api/agent on your backend:
| Method | Path | Description |
|---|---|---|
| POST | /sessions | Create chat session |
| POST | /sessions/:id/messages | Send message → AgentResult |
| GET | /sessions/:id/stream?message= | SSE stream (intent steps + recommendations) |
| GET | /health | { ok, hasLlm, hasServerProductApi } |
AgentResult
interface AgentResult {
status: "success" | "failure";
bestMatches: Product[]; // scored top picks
recommendations: Product[]; // more from search pool
productIds: string[];
steps: DialogueStep[]; // intent + scoring reasoning
}Network & contracts
Orenya's economic layer is live on Ethereum mainnet (chain ID 1). The ICO and reward distributor are transparent upgradeable proxies — always call the proxy address with the implementation ABI.
| Contract | Address |
|---|---|
| ORENYA ERC-20 | 0x8848904eCf5D2c96260137C3518522A465353D0F |
| Presale proxy | 0xd1c59a873f395f1f0ab008f3414981a219f4ce8d |
| Distributor proxy | 0x4386a65af34f5274933b9c41c91343144d96ce73 |
Proxy vs implementation
Upgrades use ProxyAdmin.upgradeAndCall. Ownership on the logic contracts uses Ownable2Step. Never fund or call the bare implementation for buys or claims.
ICO integration
Parameters: 10 × 7-day stages, soft $2M / hard $5M, 250M ORENYA on the proxy, ETH priced via Chainlink ETH/USD. User functions: buy, claim, refund.
import { parseEther } from "viem";
import { useWriteContract } from "wagmi";
import { orenyaPresaleAbi } from "@/lib/ico/abi/orenya-presale";
// Always use the PRESALE PROXY address
const PRESALE = "0xd1c59a873f395f1f0ab008f3414981a219f4ce8d";
const { writeContractAsync } = useWriteContract();
const hash = await writeContractAsync({
address: PRESALE,
abi: orenyaPresaleAbi,
functionName: "buy",
value: parseEther("0.05"),
chainId: 1,
});Site UI: /ico. Full tokenomics: /tokenomics · whitepaper.
Rewards & claims
Verified training work accrues epoch weights. A daily UTC settle builds a Merkle tree; a publisher posts the root; users claim ORENYA with a proof.
Verified work → epoch_work_credits
↓
Epoch settle (daily UTC) → StandardMerkleTree
↓
publishEpoch(epochId, root, total) on distributor proxy
↓
GET /api/rewards/epoch/claim?wallet=&epoch=
↓
claim(epochId, amount, proof) // MetaMask, user pays gas// Distributor PROXY — not the implementation
const DISTRIBUTOR = "0x4386a65af34f5274933b9c41c91343144d96ce73";
const proofRes = await fetch(
`/api/rewards/epoch/claim?wallet=${wallet}&epoch=${epochId}`,
);
const { epochIdHash, amountWei, proof } = await proofRes.json();
await writeContractAsync({
address: DISTRIBUTOR,
abi: orenyaEpochDistributorAbi,
functionName: "claim",
args: [epochIdHash, BigInt(amountWei), proof],
chainId: 1,
});| API | Purpose |
|---|---|
GET /api/rewards/epoch | Live epoch estimate |
GET /api/rewards/epoch/claim | Merkle proof for a wallet + epoch |
GET /api/wallet/portfolio | Balances, epochs, claim status |
POST /api/rewards/epoch/close | Admin settle + publish |
Default emission split: user 35% · miner 40% · validator 25% of each epoch pool (from the 300M rewards allocation). Claim UI: /portfolio.
Environment variables
# Your production deployment
MARKETPLACE_CATALOG_URL=https://api.your-marketplace.com
MARKETPLACE_API_KEY=optional
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1# Ethereum mainnet (orenya.io)
ICO_ETH_CHAIN_ID=1
NEXT_PUBLIC_ICO_ETH_CHAIN_ID=1
ICO_ETH_RPC_URL=https://ethereum.publicnode.com
ICO_ETH_SALE_ADDRESS=0xd1c59a873f395f1f0ab008f3414981a219f4ce8d
ICO_ETH_TOKEN_ADDRESS=0x8848904eCf5D2c96260137C3518522A465353D0F
ORENYA_TOKEN_ADDRESS=0x8848904eCf5D2c96260137C3518522A465353D0F
ORENYA_EPOCH_DISTRIBUTOR_ADDRESS=0x4386a65af34f5274933b9c41c91343144d96ce73
REWARD_PAYOUT_RPC_URL=https://ethereum.publicnode.com| Variable | Required | Description |
|---|---|---|
MARKETPLACE_CATALOG_URL / PRODUCT_API_URL | Yes | Base URL of your searchProducts API |
MARKETPLACE_API_KEY / PRODUCT_API_KEY | No | Bearer token for your catalog API |
LLM_API_KEY | Yes | OpenAI-compatible key for intent extraction |
LLM_BASE_URL | No | Default https://api.openai.com/v1 |
ICO_ETH_SALE_ADDRESS | ICO | Presale proxy address |
ORENYA_EPOCH_DISTRIBUTOR_ADDRESS | Rewards | Distributor proxy address |
ICO_ETH_CHAIN_ID / NEXT_PUBLIC_ICO_ETH_CHAIN_ID | Yes | 1 for Ethereum mainnet |
RAINFOREST_API_KEY | Demo only | Sample catalog on orenya.io — not for production |
Architecture
Your marketplace storefront
│ embeddable widget (customized theme + handlers)
▼
Commerce Agent API (/api/agent)
│
├─ User intent analysis (LLM extracts keywords, brand, features, budget)
├─ searchProducts(query) → YOUR catalog API
├─ Product scoring (relevance vs. user intent)
├─ Personalization (constraints, preferences, context)
└─ Recommendation generation (bestMatches + recommendations)
Your marketplace provides search. Orenya provides the intelligence layer.commerce-agent-js/
├── packages/core/ intent parsing, scoring, agent logic
├── packages/server/ REST + SSE API for your backend
├── packages/widget/ embeddable, themeable chat UI
└── examples/express-server/