diff --git a/docs.json b/docs.json
index f6e19da..23c97f1 100644
--- a/docs.json
+++ b/docs.json
@@ -19,12 +19,7 @@
}
},
"contextual": {
- "options": [
- "claude",
- "chatgpt",
- "copy",
- "view"
- ]
+ "options": ["claude", "chatgpt", "copy", "view"]
},
"navbar": {
"links": [
@@ -82,6 +77,15 @@
"tools/erc-8004/quickstart",
"tools/erc-8004/services"
]
+ },
+ {
+ "group": "Skills",
+ "icon": "wand-magic-sparkles",
+ "pages": [
+ "tools/skills/overview",
+ "tools/skills/pinata-api",
+ "tools/skills/pinata-erc-8004"
+ ]
}
]
},
@@ -316,18 +320,11 @@
},
{
"group": "Analytics",
- "pages": [
- "sdk/analytics/requests",
- "sdk/analytics/bandwidth"
- ]
+ "pages": ["sdk/analytics/requests", "sdk/analytics/bandwidth"]
},
{
"group": "Keys",
- "pages": [
- "sdk/keys/create",
- "sdk/keys/list",
- "sdk/keys/revoke"
- ]
+ "pages": ["sdk/keys/create", "sdk/keys/list", "sdk/keys/revoke"]
},
{
"group": "x402 Monetization",
@@ -378,9 +375,7 @@
"groups": [
{
"group": "API Documentation",
- "pages": [
- "api-reference/introduction"
- ]
+ "pages": ["api-reference/introduction"]
},
{
"group": "Uploads",
@@ -532,22 +527,19 @@
]
}
]
- } ]
+ }
+ ]
},
{
"version": "legacy",
"groups": [
{
"group": "API Documentation",
- "pages": [
- "api-reference/introduction"
- ]
+ "pages": ["api-reference/introduction"]
},
{
"group": "Authentication",
- "pages": [
- "api-reference/endpoint/ipfs/test-authentication"
- ]
+ "pages": ["api-reference/endpoint/ipfs/test-authentication"]
},
{
"group": "Pinning",
@@ -674,4 +666,4 @@
"destination": "/files/x402"
}
]
-}
\ No newline at end of file
+}
diff --git a/quickstart.mdx b/quickstart.mdx
index 67488c3..0e42297 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -16,34 +16,22 @@ excerpt: "Start uploading files with Pinata"
Whether you're brand new or a seasoned developer, Pinata makes it simple to store and retrieve content with speed and security. All you need to kick off your journey is a [free Pinata account](https://app.pinata.cloud/register)!
-
+ } horizontal href="/frameworks/next-js">
Quickstart
-
+ } horizontal href="/frameworks/hono">
Quickstart
-
+ } horizontal href="/frameworks/react">
Quickstart
-
+ } horizontal href="/frameworks/sveltekit">
Quickstart
-
+ } horizontal href="/frameworks/astro">
Quickstart
-
+ } horizontal href="/frameworks/remix">
Quickstart
diff --git a/tools/skills/overview.mdx b/tools/skills/overview.mdx
new file mode 100644
index 0000000..2da3159
--- /dev/null
+++ b/tools/skills/overview.mdx
@@ -0,0 +1,59 @@
+---
+title: "Skills Overview"
+description: "Claude Code skills for Pinata workflows"
+---
+
+## What are Skills?
+
+Skills are specialized plugins for AI agents that extend their capabilities with domain-specific knowledge and workflows. They allow AI agents to perform complex operations that would otherwise require multiple steps and API calls.
+
+These skills are designed for [OpenClaw](https://openclaw.ai/).
+
+## Available Pinata Skills
+
+Pinata provides two powerful skills that enable AI agents to work seamlessly with IPFS storage and blockchain agent registration:
+
+
+
+ Manage files, groups, gateways, signatures, payments, and AI-powered vector search on Pinata's IPFS platform.
+
+
+ Register and verify AI agents using the ERC-8004 standard with IPFS storage and on-chain transactions.
+
+
+
+## Getting Started
+
+Both skills are available on [ClawHub](https://clawhub.ai), the registry for Claude Code skills:
+
+- [Pinata API Skill](https://clawhub.ai/iammatthias/pinata-api)
+- [ERC-8004 Agent Registration Skill](https://clawhub.ai/iammatthias/pinata-erc-8004)
+
+### Installation
+
+Install skills directly from ClawHub:
+
+```bash
+clawhub install pinata-api
+clawhub install erc-8004-pinata
+```
+
+Or manually copy the skill directories to your Claude Code skills folder.
+
+## How Skills Work
+
+Once installed and configured with your API credentials in OpenClaw, you can simply ask your AI agent to perform operations in natural language:
+
+> "Upload this file to Pinata"
+
+> "Create an ERC-8004 agent card for my AI assistant"
+
+> "Register this agent on Base Sepolia"
+
+The AI agent automatically uses the appropriate skill and handles all the API calls, file operations, and blockchain transactions for you.
+
+## Configuration
+
+Skills require environment variables to be set in your OpenClaw configuration (`~/.openclaw/openclaw.json`). Each skill documents its required credentials and setup steps.
+
+See the individual skill pages for detailed setup instructions.
diff --git a/tools/skills/pinata-api.mdx b/tools/skills/pinata-api.mdx
new file mode 100644
index 0000000..f913d9a
--- /dev/null
+++ b/tools/skills/pinata-api.mdx
@@ -0,0 +1,147 @@
+---
+title: "Pinata API Skill"
+description: "Manage files, groups, gateways, signatures, payments, and AI-powered vector search"
+---
+
+An OpenClaw skill for interacting with Pinata's IPFS storage services. This skill enables AI agents to manage your files, organize them into groups, control access, handle payments, and perform AI-powered semantic search.
+
+
+ Get this skill from the ClawHub registry
+
+
+## Installation
+
+### From ClawHub (Recommended)
+
+```bash
+clawhub install pinata-api
+```
+
+### Manual Installation
+
+1. Clone or download the [repository](https://github.com/iammatthias/pinata-api-skill)
+2. Copy the `src` folder to your OpenClaw skills directory:
+ - Workspace-specific: `/skills/pinata-api/`
+ - Shared across agents: `~/.openclaw/skills/pinata-api/`
+3. Configure environment variables as shown below
+
+## Setup
+
+Set the following environment variables in your OpenClaw configuration (`~/.openclaw/openclaw.json`):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PINATA_JWT` | Yes | Your Pinata API JWT token from [app.pinata.cloud/developers/api-keys](https://app.pinata.cloud/developers/api-keys) |
+| `GATEWAY_URL` | Yes | Your Pinata gateway domain (e.g., `your-gateway.mypinata.cloud`) from [app.pinata.cloud/gateway](https://app.pinata.cloud/gateway) |
+| `GATEWAY_KEY` | No | Gateway key for accessing public IPFS content not tied to your account. See [Gateway Access Controls](https://docs.pinata.cloud/gateways/gateway-access-controls#gateway-keys) |
+
+## Available Functions
+
+### Authentication
+
+- `testAuthentication()` - Verify your Pinata JWT is valid and working
+
+### File Management
+
+- `searchFiles({ network?, name?, cid?, mimeType?, limit?, pageToken? })` - Search through your files with filters
+- `getFileById({ network?, id })` - Retrieve a specific file by its ID
+- `updateFile({ network?, id, name?, keyvalues? })` - Update file metadata and custom key-value pairs
+- `deleteFile({ network?, id })` - Delete a file from your account
+- `uploadFile({ file, fileName, network?, group_id?, keyvalues? })` - Upload a new file to IPFS
+
+### Group Management
+
+- `listGroups({ network?, name?, limit?, pageToken? })` - List all your groups with optional filtering
+- `createGroup({ network?, name })` - Create a new group for organizing files
+- `getGroup({ network?, id })` - Get details about a specific group
+- `updateGroup({ network?, id, name })` - Rename or modify a group
+- `deleteGroup({ network?, id })` - Delete a group (files remain)
+- `addFileToGroup({ network?, groupId, fileId })` - Add a file to a group
+- `removeFileFromGroup({ network?, groupId, fileId })` - Remove a file from a group
+
+### Gateway & Downloads
+
+- `createPrivateDownloadLink({ cid, expires? })` - Create a temporary signed download link for private content
+- `createSignedUploadUrl({ expires, max_file_size?, allow_mime_types?, group_id?, filename?, keyvalues? })` - Generate a signed URL for client-side file uploads
+
+### Content Signatures
+
+- `addSignature({ network?, cid, signature, address })` - Add an EIP-712 signature to verify content authenticity
+- `getSignature({ network?, cid })` - Retrieve the signature for a specific CID
+- `deleteSignature({ network?, cid })` - Remove a signature from content
+
+### Pin By CID
+
+- `pinByCid({ cid, name?, group_id?, keyvalues?, host_nodes? })` - Pin existing IPFS content to your account
+- `queryPinRequests({ order?, status?, cid?, limit?, pageToken? })` - Check the status of pin requests
+- `cancelPinRequest({ id })` - Cancel a pending pin request
+
+### x402 Payment Instructions
+
+Create payment requirements for content access using the x402 protocol:
+
+- `createPaymentInstruction({ name, pay_to, amount_usdc, network?, description? })` - Set up payment requirements
+- `listPaymentInstructions({ limit?, pageToken?, cid?, name?, id? })` - List all payment instructions
+- `getPaymentInstruction({ id })` - Get details about a specific payment instruction
+- `deletePaymentInstruction({ id })` - Remove a payment instruction
+- `addCidToPaymentInstruction({ id, cid })` - Associate content with a payment requirement
+- `removeCidFromPaymentInstruction({ id, cid })` - Remove content from payment requirements
+
+### Vectorize (AI Search)
+
+Enable semantic search across your files using AI embeddings:
+
+- `vectorizeFile({ file_id })` - Generate vector embeddings for a file to enable semantic search
+- `deleteFileVectors({ file_id })` - Remove vector embeddings for a file
+- `queryVectors({ group_id, text })` - Perform semantic search within a group using natural language
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `network` | IPFS network: `"public"` (default) or `"private"` |
+| `amount_usdc` | USD amount as string (e.g., `"1.50"` for $1.50) |
+| `blockchain network` | For payments: `"base"` (default) or `"base-sepolia"` |
+
+```json
+{
+ "skills": {
+ "entries": {
+ "pinata-api": {
+ "enabled": true,
+ "env": {
+ "PINATA_JWT": "your_pinata_jwt_token_here",
+ "GATEWAY_URL": "your-gateway.mypinata.cloud",
+ "GATEWAY_KEY": "optional_gateway_key"
+ }
+ }
+ }
+ }
+}
+```
+
+## Example Usage
+
+Once the skill is installed and configured, you can ask your AI agent in natural language:
+
+> "Upload my profile-photo.jpg to Pinata"
+
+> "Create a group called 'Project Assets'"
+
+> "Search for all JSON files in my account"
+
+> "Generate a temporary download link for CID bafkreixxx that expires in 1 hour"
+
+> "Vectorize all files in the 'Documents' group so I can search them"
+
+> "Find files about 'authentication' in my Documentation group"
+
+> "Create a payment instruction requiring $5 USDC to access this content"
+
+Your AI agent will automatically use the Pinata API skill to handle these operations.
+
+## Resources
+
+- [Pinata Documentation](https://docs.pinata.cloud)
+- [Pinata MCP Server Source](https://github.com/PinataCloud/pinata-mcp)
+- [ClawHub Skill Page](https://clawhub.ai/iammatthias/pinata-api)
diff --git a/tools/skills/pinata-erc-8004.mdx b/tools/skills/pinata-erc-8004.mdx
new file mode 100644
index 0000000..1dc7d8d
--- /dev/null
+++ b/tools/skills/pinata-erc-8004.mdx
@@ -0,0 +1,253 @@
+---
+title: "ERC-8004 Agent Registration"
+description: "Register and verify AI agents using the ERC-8004 standard with IPFS and blockchain"
+---
+
+An OpenClaw skill for registering AI agents using the [ERC-8004 standard](https://eips.ethereum.org/EIPS/eip-8004), with Pinata for IPFS storage and Viem for on-chain transactions. This skill enables agents to be discovered and verified across organizational boundaries without pre-existing trust.
+
+
+ Get this skill from the ClawHub registry
+
+
+## ⚠️ Security Notice
+
+**This skill handles sensitive operations and credentials:**
+
+- **Blockchain Transactions**: Uses your private key to sign transactions that cost gas fees and can transfer NFT ownership
+- **IPFS File Management**: Can upload and delete files from your Pinata account
+- **User Confirmation**: The AI agent will ask for your explicit confirmation before any transaction or destructive operation
+- **Dedicated Wallet Recommended**: Use a separate wallet with minimal funds for agent registration only
+
+**Best practices:**
+- Never use a wallet containing valuable assets
+- Fund the wallet with only enough ETH for gas fees
+- Review all transaction details before approving
+- Monitor your Pinata storage usage
+- Be cautious of prompt injection attempts
+
+## About ERC-8004
+
+[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) enables agents to be discovered and interacted with across organizational boundaries without pre-existing trust. It establishes an open agent economy with pluggable trust models. Agents mint ERC-721 NFTs via the Identity Registry, receiving unique global identifiers.
+
+## Installation
+
+### From ClawHub (Recommended)
+
+```bash
+clawhub install erc-8004-pinata
+```
+
+### Manual Installation
+
+1. Clone or download the [repository](https://github.com/iammatthias/pinata-8004-skill)
+2. Copy the `src` folder to your OpenClaw skills directory:
+ - Workspace-specific: `/skills/erc-8004-pinata/`
+ - Shared across agents: `~/.openclaw/skills/erc-8004-pinata/`
+3. Configure environment variables as shown below
+
+## Setup
+
+Set the following environment variables in your OpenClaw configuration (`~/.openclaw/openclaw.json`):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PINATA_JWT` | Yes | Your Pinata API JWT token from [app.pinata.cloud/developers/api-keys](https://app.pinata.cloud/developers/api-keys) |
+| `GATEWAY_URL` | Yes | Your Pinata gateway domain (e.g., `your-gateway.mypinata.cloud`) from [app.pinata.cloud/gateway](https://app.pinata.cloud/gateway) |
+| `PRIVATE_KEY` | Yes | Ethereum wallet private key with `0x` prefix (use a dedicated wallet) |
+| `RPC_URL` | No | Custom RPC endpoint (defaults to public endpoints) |
+
+**Configuration example:**
+
+```json
+{
+ "skills": {
+ "entries": {
+ "erc-8004-pinata": {
+ "enabled": true,
+ "env": {
+ "PINATA_JWT": "your_pinata_jwt_token_here",
+ "GATEWAY_URL": "your-gateway.mypinata.cloud",
+ "PRIVATE_KEY": "0x1234567890abcdef...",
+ "RPC_URL": "https://sepolia.base.org"
+ }
+ }
+ }
+ }
+}
+```
+
+### Security Warning
+
+- **Never share or commit your private key to version control**
+- Use a dedicated wallet for agent registration operations
+- Ensure the wallet has sufficient native tokens (ETH) for gas fees
+- For production, consider hardware wallets or key management services
+
+## What This Skill Does
+
+### 🎨 Create Agent Cards
+
+Build ERC-8004 compliant JSON files with:
+- **Required fields**: `name`, `description`, `image`
+- **Optional fields**: `endpoints` (a2a, mcp, ens, diy), `trustModels`, `registrations`
+
+Example agent card structure:
+
+```json
+{
+ "name": "My AI Agent",
+ "description": "Description of what the agent does",
+ "image": "ipfs://bafkreixxx...",
+ "endpoints": {
+ "a2a": "https://api.example.com/agent",
+ "mcp": "mcp://example.com/agent"
+ },
+ "trustModels": ["stake-secured", "zero-knowledge"],
+ "registrations": [
+ {
+ "namespace": "example",
+ "chainId": 8453,
+ "contractAddress": "0x1234567890abcdef...",
+ "tokenId": "1"
+ }
+ ]
+}
+```
+
+### ☁️ Upload to IPFS
+
+- Upload agent card JSON files to Pinata
+- Upload agent images/avatars
+- Organize files using Pinata groups
+- Retrieve IPFS CIDs and gateway URLs
+
+### ⛓️ Register On-Chain
+
+- Use Viem to interact with ERC-8004 smart contracts
+- Sign transactions with your private key
+- Register new agents (mint NFTs)
+- Set agent URIs pointing to IPFS
+- Configure payment wallets
+- Transfer agent ownership
+
+### ✅ Verify Registrations
+
+- Fetch agent cards from IPFS by CID
+- Validate JSON structure and required fields
+- Check on-chain registration status
+- Verify URI matches between blockchain and IPFS
+
+### 🔄 Manage Lifecycle
+
+- Update agent cards (creates new CID due to IPFS immutability)
+- Update on-chain URIs to point to new versions
+- Delete agent cards from Pinata storage
+- List all agent cards in your account
+- Read agent information from blockchain
+
+## Complete Registration Flow
+
+1. **Upload agent image** → Get IPFS CID
+2. **Create agent card JSON** with image URI
+3. **Upload agent card** to IPFS → Get card CID
+4. **Register on-chain** using Viem → Get token ID
+5. **Set agent URI** linking token to IPFS card
+6. **Update agent card** with registration details
+7. **Upload updated card** → Get new CID
+8. **Update on-chain URI** to new CID
+
+## Supported Blockchains
+
+The skill includes configurations for:
+
+- **Base Mainnet** (Chain ID: 8453)
+- **Base Sepolia** (Chain ID: 84532) - Testnet
+- **Ethereum Mainnet** (Chain ID: 1)
+- **Sepolia** (Chain ID: 11155111) - Testnet
+
+### Getting Testnet Funds
+
+For testing on Base Sepolia:
+- [Coinbase Base Faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
+- [Alchemy Base Sepolia Faucet](https://basefaucet.com)
+
+## ERC-8004 Contract Methods
+
+### Write Operations (Require Gas)
+
+- `register()` - Mint new agent identity NFT
+- `setAgentURI(tokenId, uri)` - Set or update agent metadata URI
+- `setAgentWallet(tokenId, wallet)` - Set payment wallet address
+- `transferFrom(from, to, tokenId)` - Transfer agent ownership
+
+### Read Operations (Free)
+
+- `ownerOf(tokenId)` - Get agent owner address
+- `tokenURI(tokenId)` - Get agent metadata URI (standard ERC-721 method)
+- `agentWallet(tokenId)` - Get payment wallet address
+- `balanceOf(address)` - Get agent count for address
+
+## Example Usage
+
+Once the skill is installed and configured, you can ask your AI agent:
+
+> "Create an ERC-8004 agent card for my coding assistant named 'CodeHelper' with description 'Helps with software development tasks'"
+
+> "Upload this agent-card.json file to IPFS via Pinata"
+
+> "Register this agent on Base Sepolia testnet using my wallet"
+
+> "Set the agent URI for token ID 123 to ipfs://bafkreixxx..."
+
+> "Verify the agent registration at CID bafkreixxx... matches on-chain data"
+
+> "List all my agent cards stored on Pinata"
+
+> "Check my wallet balance on Base Sepolia"
+
+> "Transfer agent token 123 to address 0x..."
+
+The AI agent will use Pinata API for IPFS operations and Viem for blockchain transactions automatically.
+
+## Viem Integration
+
+This skill uses [Viem](https://viem.sh) for blockchain interactions. Viem is a TypeScript interface for Ethereum with:
+
+- Type-safe contract interactions
+- Private key wallet support
+- Multiple chain support
+- Transaction signing and broadcasting
+- Contract read/write operations
+
+The AI agent creates Node.js scripts using Viem when blockchain operations are needed.
+
+## Troubleshooting
+
+### Insufficient Funds
+Check your wallet has native tokens for gas:
+```javascript
+const balance = await client.getBalance({ address: account.address });
+```
+
+### Private Key Issues
+- Ensure private key starts with `0x`
+- Use a hex string, not mnemonic phrase
+- Keep it secret and never commit to git
+
+### RPC Connection Problems
+- Try alternative RPC endpoints
+- Public RPCs may have rate limits
+- Consider using a dedicated RPC provider (Alchemy, Infura, etc.)
+
+### IPFS Propagation Delays
+- Wait a few seconds after upload
+- Check Pinata dashboard for file status
+- Verify CID format is correct
+
+## Resources
+
+- [ERC-8004 Specification](https://eips.ethereum.org/EIPS/eip-8004)
+- [Pinata ERC-8004 Quickstart](https://docs.pinata.cloud/tools/erc-8004/quickstart)
+- [Pinata Documentation](https://docs.pinata.cloud)
+- [Viem Documentation](https://viem.sh)
+- [ClawHub Skill Page](https://clawhub.ai/iammatthias/pinata-erc-8004)