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 providesCommerce Agent handles
searchProducts(query) — product retrievalUser intent analysis (LLM)
Catalog data (IDs, titles, prices, images)Product scoring vs. shopper intent
Checkout, inventory, fulfillmentPersonalization and constraint matching
Your brand, theme, and UXRecommendation 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

PackageRole
@commerce-agent/coreIntent parsing, scoring, agent orchestration
@commerce-agent/serverREST + SSE API for your backend
@commerce-agent/widgetEmbeddable, 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:

EndpointPurpose
GET /search/find_productSearch — equivalent to searchProducts(query)
GET /search/view_product_informationProduct details for scoring (attributes, descriptions)
Catalog contracttypescript
// 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 });
}
Product shapetypescript
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.

SDKbash
npm install commerce-agent-js

Quick start

Connect your marketplace catalog and LLM key:

Express servertypescript
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);
Embed widgethtml
<!-- 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.

Custom marketplacetypescript
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 matches

Server

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.

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

Production embedhtml
<!-- 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:

javascript
// 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:

MethodPathDescription
POST/sessionsCreate chat session
POST/sessions/:id/messagesSend message → AgentResult
GET/sessions/:id/stream?message=SSE stream (intent steps + recommendations)
GET/health{ ok, hasLlm, hasServerProductApi }

AgentResult

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

ContractAddress
ORENYA ERC-200x8848904eCf5D2c96260137C3518522A465353D0F
Presale proxy0xd1c59a873f395f1f0ab008f3414981a219f4ce8d
Distributor proxy0x4386a65af34f5274933b9c41c91343144d96ce73

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.

buy() via wagmitypescript
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.

Claim pipelinetext
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
claim() via wagmitypescript
// 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,
});
APIPurpose
GET /api/rewards/epochLive epoch estimate
GET /api/rewards/epoch/claimMerkle proof for a wallet + epoch
GET /api/wallet/portfolioBalances, epochs, claim status
POST /api/rewards/epoch/closeAdmin 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

Production marketplacebash
# 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
Mainnet contractsbash
# 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
VariableRequiredDescription
MARKETPLACE_CATALOG_URL / PRODUCT_API_URLYesBase URL of your searchProducts API
MARKETPLACE_API_KEY / PRODUCT_API_KEYNoBearer token for your catalog API
LLM_API_KEYYesOpenAI-compatible key for intent extraction
LLM_BASE_URLNoDefault https://api.openai.com/v1
ICO_ETH_SALE_ADDRESSICOPresale proxy address
ORENYA_EPOCH_DISTRIBUTOR_ADDRESSRewardsDistributor proxy address
ICO_ETH_CHAIN_ID / NEXT_PUBLIC_ICO_ETH_CHAIN_IDYes1 for Ethereum mainnet
RAINFOREST_API_KEYDemo onlySample catalog on orenya.io — not for production

Architecture

Request flowtext
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.
Repository layouttext
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/
Connect wallet to try