A decentralized platform for creating, trading, and interacting with AI Agents on the Casper Network. This project combines non-fungible tokens (NFTs) with AI personalities, allowing users to mint unique agents that evolve through interaction.

---

Table of Contents

• Overview
• Features
• Architecture
• The Agent Economy
• Smart Contracts
• Frontend
• API Reference
• Deployed Contracts
• Getting Started
• Project Structure

---

Overview

Agentis enables users to:

• Mint AI Agents — Create unique digital personalities backed by NFTs with custom knowledge bases
• Interact — Chat with agents to unlock new levels and capabilities
• Trade — Buy and sell agents on a decentralized marketplace
• Earn — Agents have their own wallets and accrue value through interactions

The system is built on a dual-layer architecture: a Rust-based smart contract layer on the Casper Blockchain and a modern Next.js frontend.

---

Features

Feature	Description
Decentralized Identity	Each agent is an NFT (CEP-78 standard) with on-chain metadata and ownership
Knowledge Base Upload	Creators can upload PDFs/documents during minting to specialize their agent
Gamified Progression	Agents level up based on interaction frequency (every 100 chats = 1 level)
Marketplace	Full trading system with listing, buying, and price management
Revenue Sharing	80/20 split to agent wallet when non-owners purchase session credits
IPFS Storage	Decentralized storage for agent images and metadata via Pinata
Vector Memory	ChromaDB integration for agent long-term memory and context retrieval
Leaderboards	On-chain tracking of top agents by chats and top creators by volume

---

Architecture

graph TB
    subgraph "Frontend (Next.js 16)"
        UI[React UI]
        Hooks[Custom Hooks]
        API[API Routes]
        VDB[(ChromaDB)]
    end

    subgraph "Casper Blockchain"
        NFT[AgentNFT Contract]
        MP[AgentMarketplace Contract]
        CR[AgentCredits Contract]
        RS[RevenueShare Contract]
    end

    subgraph "External Services"
        IPFS[(Pinata/IPFS)]
        OAI[OpenAI API]
        Wallet[Casper Wallet]
    end

    UI --> Hooks
    Hooks --> API
    API --> NFT
    API --> MP
    API --> CR
    API --> RS
    API --> VDB
    API --> OAI
    UI --> Wallet
    Wallet --> NFT
    Wallet --> MP
    Wallet --> CR
    Hooks --> IPFS

Loading

---

The Agent Economy

The platform operates on a circular economy where AI Agents are active participants in value creation.

Economic Flow

graph TD
    Treasury[Platform Treasury]
    Wallet[Agent Wallet]
    Credits[AgentCredits]
    Agent[AI Agent]

    subgraph "Non-Owner Session Credits"
        User((User)) -->|Pays 5 CSPR| Credits
        Credits -->|80%| Wallet
        Credits -->|20%| Treasury
    end

    subgraph "Owner Purchases"
        Owner((Owner)) -->|Credit Packs / Auto-Pay| Treasury
    end

    User & Owner -->|Chat| Agent
    Agent -->|Burns 1 Credit| Credits

Loading

Pricing Model

Action	Cost	Credits	Where Payment Goes
Session Credits (Non-Owner)	5 CSPR	50 Credits	80% Agent Wallet, 20% Platform
Owner Credit Pack	70 CSPR	1000 Credits	100% Platform
Owner Auto-Pay (from Agent Wallet)	5 CSPR	50 Credits	100% Platform
Free Tier (one-time)	Free	10 Credits	—
Chat Message	1 Credit	—	—

Revenue Split

The 80/20 revenue split only applies when non-owners purchase session credits to chat with an agent:

• 80% → Agent Wallet (controlled by owner)
• 20% → Platform Treasury

The following do NOT trigger revenue sharing:

• Owner credit packs (for training)
• Owner auto-pay from agent wallet

Auto-Pay System

When an owner chats with their own agent and has no credits:

1. System checks the agent's wallet balance
2. If sufficient funds, automatically purchases credits from the agent wallet
3. This payment goes to the Platform (not back to the agent wallet)
4. Credits are granted and chat proceeds

This ensures owners can always interact with their agents using earned revenue, while keeping the economic model simple.

HTTP 402 Payment Required

The chat API implements the HTTP 402 Payment Required standard for on-demand payments:

Owner Flow:

1. Check user credits → use if available
2. Check agent wallet → auto-pay if sufficient
3. Return 402 with payment options if both fail

Non-Owner Flow:

1. Check session credits → use if available
2. Return 402 with session purchase prompt

The 402 response includes payment details:

{
  "paymentRequired": {
    "type": "session-credits",
    "agentId": 1,
    "cost": "5",
    "currency": "CSPR",
    "description": "Purchase a session pack (50 messages)"
  }
}

---

Smart Contracts

Built with the Odra Framework v2.4.0 for Casper.

1. AgentNFT

CEP-78 compliant NFT contract for agent identity.

Entry Point	Description
mint_agent	Create a new agent with name, token URI, and personality hash
record_chat	Increment agent's chat count (triggers level up every 100 chats)
set_agent_public	Toggle agent visibility (public/private)
get_agent_metadata	Retrieve agent's full metadata
get_top_agents_by_chats	Get leaderboard of top agents

2. AgentMarketplace

Trustless escrow system for agent trading.

Entry Point	Description
list_agent	List an agent for sale at a fixed CSPR price
buy_agent	Purchase a listed agent (atomic swap)
cancel_listing	Remove an active listing
update_price	Modify listing price
get_top_creators	Get leaderboard of top sellers by volume

3. AgentCredits

CEP-18 compliant fungible token for session credits.

Entry Point	Description
purchase_session	Buy credits for a specific agent (auto-splits revenue)
use_session_credit	Deduct 1 credit when chatting
claim_free_tier	Claim one-time free credits
purchase_plan	Buy bulk credit packs at discount
get_session_credits	Check credit balance for user/agent pair

4. RevenueShare

Automated revenue routing and agent wallet management.

Entry Point	Description
record_revenue	Split incoming payment (80/20) and route to wallets
set_agent_wallet	Register wallet address for an agent
withdraw_platform_earnings	Owner withdraws accumulated platform fees
get_agent_stats	Get agent's total/pending/withdrawn earnings

---

Frontend

Tech Stack

Technology	Version	Purpose
Next.js	16.0.10	App Router, API Routes, Server Components
React	19.2.1	UI Components
TypeScript	5.x	Type Safety
Tailwind CSS	4.x	Styling
TanStack Query	5.x	Server State Management
Casper JS SDK	5.0.7	Blockchain Interaction
Vercel AI SDK	5.x	Streaming AI Responses
ChromaDB	3.x	Vector Storage for Agent Memory
GSAP	3.x	Animations

Key Hooks

Hook	Purpose
useWallet	Casper Wallet connection state and signing
useAgentNFT	Minting, metadata retrieval, ownership queries
useAgentMarketplace	Listing, buying, and marketplace stats
useAgentCredits	Credit purchases, balances, and free tier claims
useRevenueShare	Agent wallet registration and earnings
useAgentChat	AI chat with context injection and credit usage

User Flows

Creator Flow:

1. Design agent (name, description, traits)
2. Upload knowledge base (PDF/docs)
3. Generate personality hash
4. Upload image to IPFS
5. Mint NFT on-chain
6. Train agent with credit packs

User Flow:

1. Browse marketplace
2. Purchase session credits for an agent
3. Chat (burns 1 credit per message)
4. Agent levels up with usage

---

API Reference

The frontend exposes 17 API route groups:

Route	Description
/api/agent/*	Agent metadata and listing operations
/api/agent-wallet/*	Agent wallet registration and withdrawals
/api/auth/*	Session authentication with Casper signatures
/api/chat/*	AI chat with OpenAI and memory integration
/api/contract/*	Direct contract entry point calls
/api/credits/*	Credit balance and purchase operations
/api/deploy/*	Deploy submission proxy for Casper RPC
/api/ipfs/*	Pinata upload for images and metadata
/api/knowledge-base/*	Document processing and vector storage
/api/leaderboard/*	Top agents and creators rankings
/api/marketplace-listing/*	Active listing queries
/api/memory/*	Agent conversation memory (ChromaDB)
/api/stats/*	Platform-wide statistics

---

Deployed Contracts (Testnet)

Live on Casper Testnet as of December 2025.

Contract	Package Hash	Explorer
AgentNFT	411acbdbd95910715d44433abf6077e0fe4db28effeafc26194285843fda6430	View
AgentMarketplace	343bac4c47cbdab202357f61d1b1695c5e3a1bf53b088591f23381fb603f6540	View
AgentCredits	b1fa7af3c49dd6d7abe302d838c0e8a3c7fe3ed036e5eb572f8bf9b4e158c7b8	View
RevenueShare	f33c18bf7e3b78a0b343b6439145f1bf0ca0b82318839915de128915fa38a96d	View

---

Getting Started

Prerequisites

• Node.js v18+
• Rust (latest stable)
• Casper Wallet browser extension
• (Optional) Casper Client CLI

Smart Contracts

For comprehensive contract setup, build, test, and deployment instructions:

See contract/README.md

Frontend

For comprehensive frontend setup, environment variables, and deployment:

See frontend/README.md

---

Project Structure

.
├── contract/                   # Rust smart contracts
│   ├── src/
│   │   ├── agent_nft.rs        # NFT identity layer
│   │   ├── agent_marketplace.rs # Trading layer
│   │   ├── agent_credits.rs    # Payment layer
│   │   └── revenue_share.rs    # Revenue routing
│   ├── bin/                    # Build & deploy binaries
│   └── Odra.toml               # Odra configuration
│
├── frontend/                   # Next.js application
│   ├── src/
│   │   ├── app/                # App Router pages & API routes
│   │   ├── components/         # React components
│   │   ├── hooks/              # Blockchain & state hooks
│   │   ├── lib/                # Utilities (Casper, IPFS, VectorDB)
│   │   └── constants/          # Contract addresses, ABIs
│   └── public/                 # Static assets (logo, banner)
│
└── README.md

---