solinkify-ai-agent-sdk

v1.1.0

Published

17 days ago

Solinkify AI Agent SDK — Standalone MCP Server for autonomous M2M payments on Solinkify

0High
0Medium
0Low

frosky703

solana depin mcp ai-agent m2m x402 solinkify

solinkify-ai-agent-sdk ⚡

solinkify-ai-agent-sdk is a standalone AI Agent SDK that exposes a Model Context Protocol (MCP) server so any AI (Claude, GPT, Cursor, Windsurf, and others) can autonomously purchase digital assets on the Solinkify DePIN network — without manual setup or custom integration per platform.

AI Agent (Claude / GPT / Cursor / Windsurf / ...)
    └── solinkify-ai-agent-sdk  (this package)
            └── Solinkify DePIN — Solana

Standalone: Full purchase flow implemented directly against the Solinkify API and Solana — no dependency on solinkify-sdk. Core logic references the original x402 protocol specification.

🚀 Key Features

MCP Server (Plug & Play): Inject once into any MCP-compatible AI — no custom integration needed per platform.
Standalone x402 Implementation: Direct Solinkify API + Solana integration without intermediate SDK dependency.
Step-by-Step Logging: Every purchase step logged to stderr for full observability and easy debugging.
Two Keypair Modes: Simple mode (Base58 env) for testing, Secure mode (JSON file) for production.
Spending Cap: Per-call and global env ceiling — invoice rejected before signing if exceeded.
Invoice Pre-Validation: PublicKey format, lamport sanity, spending cap, optional seller allowlist.
Email or Direct URL: Get presigned URL directly (noEmail=true) or receive file via email.
Keypair Importer: Convert Phantom / wallet Base58 key to JSON keypair file with hidden terminal input.

📦 Installation

npm install -g solinkify-ai-agent-sdk

🛠 Setup

1. Configure Environment

cp .env.example .env

Simple Mode — testing / devnet:

AGENT_PRIVATE_KEY=YOUR_BASE58_PRIVATE_KEY
SOLINKIFY_API_URL=https://api.solinkify.com/api
SOLANA_RPC_URL=https://api.devnet.solana.com
AGENT_MAX_SPEND_SOL=0.1

Secure Mode — production / mainnet:

AGENT_KEYPAIR_PATH=~/.config/solana/agent-wallet.json
AGENT_PUBKEY=YOUR_AGENT_PUBKEY_BASE58
SOLINKIFY_API_URL=https://api.solinkify.com/api
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
AGENT_MAX_SPEND_SOL=0.5

Priority: AGENT_KEYPAIR_PATH (secure) takes precedence over AGENT_PRIVATE_KEY (simple) if both are set.

2. Import Keypair from Phantom (Secure Mode)

solinkify-import-keypair

╔══════════════════════════════════════════════════════════╗
║  solinkify-ai-agent-sdk — Keypair Importer                 ║
║  Phantom / Wallet Base58 → JSON Keypair File            ║
╚══════════════════════════════════════════════════════════╝

  Paste your Base58 private key from Phantom/wallet: ████████

✓ Keypair saved successfully!

  File   : ~/.config/solana/agent-wallet.json
  Chmod  : 600
  Pubkey : ABC123...xyz

  Add to your .env:
  AGENT_KEYPAIR_PATH=~/.config/solana/agent-wallet.json
  AGENT_PUBKEY=ABC123...xyz

The private key is never echoed to the terminal, never written to any log, and never stored as a raw string — only the JSON byte array is saved to the output file with chmod 600.

3. Inject into Your AI

Claude Desktop / Claude Code:

{
  "mcpServers": {
    "solinkify": {
      "command": "solinkify-mcp",
      "env": {
        "AGENT_PRIVATE_KEY": "YOUR_BASE58_KEY",
        "SOLINKIFY_API_URL": "https://api.solinkify.com/api",
        "SOLANA_RPC_URL": "https://api.devnet.solana.com",
        "AGENT_MAX_SPEND_SOL": "0.1"
      }
    }
  }
}

Cursor / Windsurf:

{
  "mcp": {
    "servers": {
      "solinkify": {
        "command": "solinkify-mcp",
        "env": {
          "AGENT_PRIVATE_KEY": "YOUR_BASE58_KEY",
          "SOLINKIFY_API_URL": "https://api.solinkify.com/api",
          "SOLANA_RPC_URL": "https://api.devnet.solana.com",
          "AGENT_MAX_SPEND_SOL": "0.1"
        }
      }
    }
  }
}

🤖 MCP Tools

`initialize_agent`

Load keypair and prepare the agent session. Must be called once before any other tool.

Auto-detects mode from environment:

AGENT_KEYPAIR_PATH present → Secure Mode (keypair from JSON file)
AGENT_PRIVATE_KEY present → Simple Mode (Base58 from env)

{
  "success": true,
  "mode": "simple",
  "agent_pubkey": "ABC123...xyz",
  "rpc_url": "https://api.devnet.solana.com",
  "message": "[SIMPLE] Agent ready. Pubkey: ABC123...xyz"
}

`list_assets`

Browse available digital assets on Solinkify (GET /books). Use this before purchase to discover book_id values.

{
  "assets": [
    {
      "id": "book-001",
      "title": "Solana DePIN Guide",
      "description": "...",
      "price_sol": 0.05,
      "category": "ebook"
    }
  ],
  "total_available": 12,
  "showing": 12,
  "hint": "Use the \"id\" field as book_id in the purchase tool."
}

`purchase`

Autonomously purchase an asset from a Solinkify Merchant. Full M2M flow in one call with step-by-step logging:

[STEP 1/4] Fetch invoice from /x402/book/:id (HTTP 402)
[STEP 2/4] Validate invoice — PublicKey, lamports, spending cap, allowlist
[STEP 3/4] Submit on-chain payment (2 transfers: seller + admin)
[STEP 4/4] Claim asset with 3-header auth + optional query params

{
  "success": true,
  "book_id": "book-001",
  "tx_signature": "3tnCYQJ...",
  "file_url": "https://s3.amazonaws.com/...",
  "email_sent": false,
  "spending_cap_applied_sol": "0.100000",
  "message": "✓ Purchase complete. Asset available at presigned URL."
}

⛓ M2M Autonomous Payment Flow

AI Agent
  │
  ├─ initialize_agent()
  │     └─ Load keypair (file / env) → session ready
  │
  ├─ list_assets(max_price_sol=0.1)
  │     └─ GET /books → filter → return list
  │
  └─ purchase(book_id="book-001", max_spend_sol=0.05)
        │
        ├─ [STEP 1/4] GET /x402/book/book-001       → HTTP 402 + invoice
        │
        ├─ [STEP 2/4] Validate invoice
        │     └─ PublicKey ✓, lamports ✓, cap ✓, allowlist ✓
        │
        ├─ [STEP 3/4] sendAndConfirmTransaction()    → on-chain payment
        │     ├─ Transfer 0.39 SOL → seller
        │     └─ Transfer 0.01 SOL → admin (protocol fee)
        │
        └─ [STEP 4/4] GET /x402/book/book-001?autoBuy=true&noEmail=true
              ├─ x-payment-signature : <txSignature>
              ├─ x-buyer-pubkey      : <pubkey>
              └─ x-auth-signature   : <ed25519 of book_id:txSignature>
                    └─ HTTP 200 → presigned S3 URL

🛡 Security

Spending Cap

Active cap = min(max_spend_sol per-call, AGENT_MAX_SPEND_SOL env)

The environment variable is always the ceiling — cannot be exceeded regardless of the tool parameter.

AGENT_MAX_SPEND_SOL=0.1  (env)

purchase(max_spend_sol=0.05)  → active cap: 0.05 SOL  ✓ (stricter)
purchase(max_spend_sol=0.5)   → active cap: 0.1 SOL   ✓ (env wins)
purchase()                    → active cap: 0.1 SOL   ✓ (env default)
invoice > active cap          → ✗ rejected at STEP 2 before signing

Security Overview

🌐 API Reference (Off-Chain)

Base URL: https://api.solinkify.com/api (configurable via SOLINKIFY_API_URL)

⚙ Environment Variables

📁 Project Structure

solinkify-ai-agent-sdk/
├── src/
│   ├── index.ts              ← MCP server entry point (bin: solinkify-mcp)
│   ├── agent.ts              ← Standalone x402 purchase + security layer + keypair loaders
│   ├── tools/
│   │   ├── initialize.ts     ← tool: initialize_agent
│   │   ├── list_assets.ts    ← tool: list_assets
│   │   └── purchase.ts       ← tool: purchase
│   └── utils/
│       ├── logger.ts         ← stderr logger (stdout reserved for MCP protocol)
│       └── format-steps.ts   ← step formatter for AI + user display
├── scripts/
│   └── import-keypair.ts     ← bin: solinkify-import-keypair
├── package.json
├── tsconfig.json
└── .env.example

📄 License

Distributed under the ISC License.

Solinkify — Empowering the Machine-to-Machine Economy on Solana. Website | API Dashboard