Plan: Pinata OpenClaw Agents with OpenRouter

Context

The architecture specifies 3 AI agents (Buyer, Seller, Admin) hosted on Pinata's OpenClaw platform (agents.pinata.cloud). Currently, these agents are implemented as a self-hosted MCP server in mcp-agents/ using LangChain + NVIDIA Nemotron direct API. The goal is to create the OpenClaw skill packages so these agents can be deployed on Pinata with OpenRouter as the LLM provider, as originally designed.

Model: nvidia/nemotron-3-nano-30b-a3b via OpenRouter (the Nemotron Ultra 253B from mcp-agents is not on OpenRouter; this 30B MoE model is purpose-built for agentic AI with 256K context).

Backend status: Already wired up — backend/src/routes/agents.routes.ts has POST /agents/chat, and backend/src/services/agent.service.ts routes to PINATA_BUYER_AGENT_URL, PINATA_SELLER_AGENT_URL, PINATA_ADMIN_AGENT_URL env vars. Just needs the URLs once agents are deployed.

mcp-agents/: Kept as-is for local dev/testing fallback.

What We're Creating

A new pinata-agents/ directory with 15 OpenClaw skill packages (one per tool) organized by agent, plus agent personality configs and a setup guide.

Directory Structure

pinata-agents/
├── README.md                          # Setup guide for Pinata dashboard
├── agents/
│   ├── buyer-agent.md                 # Personality + system prompt config
│   ├── seller-agent.md                # Personality + system prompt config
│   └── admin-agent.md                 # Personality + system prompt config
├── skills/
│   ├── buyer/
│   │   ├── order-status/
│   │   │   ├── SKILL.md               # YAML frontmatter + description
│   │   │   └── index.js               # HTTP call to Flow State API
│   │   ├── track-shipment/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   ├── file-dispute/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   ├── get-receipt/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   └── list-my-orders/
│   │       ├── SKILL.md
│   │       └── index.js
│   ├── seller/
│   │   ├── list-orders/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   ├── get-metrics/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   ├── confirm-label/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   ├── respond-dispute/
│   │   │   ├── SKILL.md
│   │   │   └── index.js
│   │   └── get-payouts/
│   │       ├── SKILL.md
│   │       └── index.js
│   └── admin/
│       ├── get-analytics/
│       │   ├── SKILL.md
│       │   └── index.js
│       ├── list-sellers/
│       │   ├── SKILL.md
│       │   └── index.js
│       ├── flagged-sellers/
│       │   ├── SKILL.md
│       │   └── index.js
│       ├── webhook-logs/
│       │   ├── SKILL.md
│       │   └── index.js
│       └── gas-report/
│           ├── SKILL.md
│           └── index.js

Total: 30 files (15 SKILL.md + 15 index.js) + 3 agent configs + 1 README

Skill Format

Each SKILL.md follows OpenClaw's format:

---
name: order-status
description: Get the full status, financials, and shipping info of a buyer's order
env:
  - FLOWSTATE_API_KEY
  - FLOWSTATE_API_URL
---

## Usage
Call this skill with an `order_id` to get the current state of a buyer's order.

## Parameters
- `order_id` (string, required): The order ID to look up

## Returns
Order state, items, totals, escrow details, shipping info, and state history.

Each index.js makes an HTTP call to the Flow State backend API:

const API_URL = process.env.FLOWSTATE_API_URL || 'https://api.flowstate.xyz';
const API_KEY = process.env.FLOWSTATE_API_KEY;

async function run({ order_id }) {
  const res = await fetch(`${API_URL}/api/v1/orders/${order_id}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` },
  });
  if (!res.ok) throw new Error(`API returned ${res.status}`);
  return await res.json();
}

Skill Mapping (mcp-agents tool → OpenClaw skill)

Buyer Skills

Seller Skills

Admin Skills

Agent Configs (for Pinata Dashboard)

Each agent config file documents what to enter in the Pinata dashboard:

Pinata Secrets Vault (per agent)

• OPENROUTER_API_KEY — OpenRouter API key
• FLOWSTATE_API_KEY — Flow State backend API key
• FLOWSTATE_API_URL — Backend URL (e.g., https://api.flowstate.xyz)

README.md (Setup Guide)

Step-by-step guide covering:

1. Prerequisites (Pinata paid plan, OpenRouter API key, Flow State API key)
2. Uploading skills to Pinata (pin each skill folder to IPFS)
3. Creating each agent on agents.pinata.cloud (4-step wizard)
4. Configuring secrets in the Pinata Secrets Vault
5. Getting the agent chat URLs
6. Setting PINATA_BUYER_AGENT_URL, PINATA_SELLER_AGENT_URL, PINATA_ADMIN_AGENT_URL in the backend .env
7. Testing the agents via the Pinata chat interface

Implementation Order

1. Create pinata-agents/ directory structure
2. Write the 3 agent personality configs (agents/*.md)
3. Write all 15 SKILL.md files with proper YAML frontmatter
4. Write all 15 index.js skill scripts (HTTP calls to Flow State API)
5. Write the README.md setup guide
6. Update architecture.md Sub-Component 6 to reflect the model change to nvidia/nemotron-3-nano-30b-a3b

Key Differences from mcp-agents

Files to Reference

• mcp-agents/src/tools/buyer-tools.ts — tool logic to port to skills
• mcp-agents/src/tools/seller-tools.ts — tool logic to port to skills
• mcp-agents/src/tools/admin-tools.ts — tool logic to port to skills
• mcp-agents/src/agents/buyer-agent.ts — system prompt to reuse
• mcp-agents/src/agents/seller-agent.ts — system prompt to reuse
• mcp-agents/src/agents/admin-agent.ts — system prompt to reuse
• backend/src/routes/agents.routes.ts — already has POST /agents/chat
• backend/src/services/agent.service.ts — already routes to PINATA_*_AGENT_URL
• backend/src/config/env.ts — already has PINATA_*_AGENT_URL env vars
• .claude/architecture.md — update Sub-Component 6

Verification

1. Skill structure: Each skill folder has valid SKILL.md with YAML frontmatter + index.js
2. API calls: Each index.js correctly targets the right Flow State API endpoint
3. Agent configs: System prompts match the mcp-agents personality prompts
4. Dashboard guide: README covers the full Pinata agent creation flow
5. Backend wiring: Confirm PINATA_*_AGENT_URL env vars in backend/src/config/env.ts are ready to accept the deployed agent URLs