Tag-per-Track AgentKit Tool 🎸🤖

An Agentic-First LangChain/AgentKit tool designed to enable AI Agents to perform advanced audio analysis while handling on-chain micro-payments autonomously via the x402 protocol (HTTP 402 Payment Required).

🌟 Overview

This tool allows AI agents to submit audio files (via URL) to the Tag-per-Track API. In exchange for a small fee (e.g., 0.05 USDC on Base Mainnet), the agent receives a rich JSON payload containing:

• BPM & Rhythm
• Key & Scale
• Genres (with confidence scores)
• Moods & Instruments

What makes this unique is that the agent handles the payment itself using a Server-Managed Coinbase CDP Wallet, signing an EIP-3009 TransferWithAuthorization without any human intervention.

🚀 Key Features

• Standardized Payment: Implements the x402 standard for frictionless monetized APIs.
• Coinbase CDP Integrated: Native support for Coinbase SDK Managed Wallets.
• Agentic Signing: Uses EIP-712 typed data signing for secure, gasless-for-user transactions.
• LangChain Compatible: Ready to be plugged into any AgentExecutor or LangChain agent.

🛠 Prerequisites

• Base Mainnet: The current implementation runs on the Base Mainnet.
• USDC (Base Mainnet): Ensure your agent's wallet has USDC.
• Coinbase CDP API Keys: You need CDP_API_KEY_NAME and CDP_API_KEY_PRIVATE_KEY.

📦 Setup

1. Installation

npm install

2. Environment Variables

Create a .env.local file at the project root:

# Coinbase CDP Credentials (from your project dashboard)
CDP_API_KEY_NAME="organizations/..."
CDP_API_KEY_PRIVATE_KEY="-----BEGIN ANY KEY-----..."

# The Seed for your agent's persistent wallet (keep this safe!)
CDP_WALLET_SECRET="your-cdp-shared-secret"

3. Wallet Setup (Provisioning)

If it's your agent's first time, run the setup script to create the wallet. Once created, you will need to manually send some ETH (for gas) and USDC (for payments) to the generated address on Base Mainnet:

npm run setup-wallet

(Note: If you are building/testing on Base Sepolia, you can append -- testnet to this command. The script will automatically call the testnet faucet to fund your agent's wallet with free test ETH and USDC).

💻 Usage Example

To use this tool, your agent needs a wallet capable of signing EIP-712 messages (e.g., using Viem or Coinbase CDP SDK).

import { createTagPerTrackTool } from 'tag-per-track-agentkit';
import { cdpWallet } from './your-cdp-config'; // Custom CDP setup

// 1. Initialize your agent's tool
const tagPerTrackTool = createTagPerTrackTool(cdpWallet);

// 2. Add to LangChain Agent tools array
const tools = [tagPerTrackTool, ...otherTools];

// 3. The Agent can now analyze music!
// Prompt: "Analyze the genre and BPM of this track: https://example.com/song.mp3"

⚡ How it Works (The x402 Cycle)

1. Initial Call: The Agent calls the API without a proof. The API returns HTTP 402 Payment Required along with payment instructions.
2. Challenge Extraction: The TagPerTrackTool parses the paymentRequirements (amount, asset, payTo).
3. EIP-3009 Signing: The agent signs a TransferWithAuthorization EIP-712 message using its CDP-managed wallet.
4. Resubmission: The tool sends a second request with the signed X-Payment-Proof header.
5. Verification & Execution: The backend verifies the signature on-chain, settles the payment, and triggers the audio analysis.

📁 Project Structure

tag-per-track-agentkit/
├── src/
│   ├── TagPerTrackTool.ts    # Main LangChain tool (x402 payment cycle)
│   ├── builderCode.ts        # On-chain attribution utilities
│   ├── test-connector.ts     # End-to-end test script
│   └── setup-wallet.ts       # Mainnet wallet provisioning script
├── .env.example              # Environment variable template
├── package.json
└── tsconfig.json

🛠 Scripts

• npm run test:connector — Runs a full end-to-end test of the tool.
• npm run setup-wallet — Provisions the agent's wallet on Base Mainnet (use -- testnet for Sepolia).
• npm run build — Compiles the TypeScript code.
• npm run clean — Removes the dist/ output directory.

API Documentation & Under the Hood

This SDK is a wrapper around the core Tag-per-Track API. If you want to explore the underlying REST endpoints, inspect the precise JSON schemas returned by our Essentia/TensorFlow models, or test the inference manually, check out our interactive Swagger UI:

👉 Tag-per-Track API Swagger Documentation

Built for the Agentic Commerce era. 🚀