Introduction to ShieldX

ShieldX is the first non-custodial security middleware purpose-built for AI agents that handle cryptocurrency. It sits between your agent and the blockchain, enforcing spending rules, managing approvals, and maintaining a complete audit trail — all without ever touching your private keys.

How It Works

At a high level, ShieldX wraps your wallet in a smart contract that enforces rules before any transaction executes. Your agent communicates through the ShieldX API, and every action is validated against your rule set in real-time.

Key Principles

Quick Start

Get ShieldX running in under 60 seconds. This guide walks you through creating your first agent, setting spending rules, and sending a test transaction.

# Python
pip install shieldx

# TypeScript
npm install @shieldx/sdk

# Go
go get github.com/shieldx/go-sdk

from shieldx import ShieldX

sx = ShieldX(api_key="sx_live_...")

agent = sx.agents.create(
    name="TradingBot",
    chain="solana",
    description="Automated portfolio rebalancer"
)

print(f"Agent ID: {agent.id}")
print(f"Wallet: {agent.wallet_address}")

sx.rules.create(
    agent_id=agent.id,
    rules=[
        {"type": "per_tx_limit", "value": 500},
        {"type": "daily_budget", "value": 2000},
        {"type": "whitelist", "addresses": [
            "0x1234...5678",
            "0xabcd...ef01"
        ]},
        {"type": "time_window", "start": "09:00",
         "end": "18:00", "timezone": "UTC"},
    ]
)

result = sx.payments.create(
    agent_id=agent.id,
    amount="250.00",
    token="USDC",
    recipient="0x1234...5678",
    reason="Portfolio rebalance — ETH allocation"
)

# result.status: "auto_approved" | "pending" | "denied"
# result.tx_hash: "0xabc...def"
print(f"Status: {result.status}")
print(f"TX: {result.tx_hash}")

Architecture

A deep dive into how ShieldX processes transactions, enforces rules, and maintains security across the stack.

Layer Stack

ShieldX operates as middleware between your agent and the blockchain. Each layer adds a specific security capability.

Smart Wallets

Each agent gets a dedicated smart contract wallet with built-in rule enforcement. Non-custodial by design — your keys, your funds.

Rules Engine

12 composable permission layers that define exactly what your agents can and cannot do. Rules are evaluated in order — all must pass for a transaction to execute.

Session Keys

Temporary, scoped cryptographic keys that give agents limited access without exposing the master key. Agents operate with just enough permission — nothing more.

session = sx.sessions.create(
    agent_id=agent.id,
    permissions=[
        "transfer:usdc",
        "transfer:sol",
    ],
    limits={
        "per_tx": 500,
        "daily": 2000,
    },
    expires_in="24h",       # auto-expire
    allowed_chains=["solana"],
)

# Session key is scoped and temporary
print(f"Session: {session.key}")
print(f"Expires: {session.expires_at}")

Approval Flow

Transactions that exceed your auto-approve thresholds are held in a queue and routed to you for manual review via Telegram, email, or push notification.

Notification Channels

REST API

A simple, RESTful API to manage agents, rules, transactions, and approvals. All endpoints return JSON and use standard HTTP status codes.

https://api.shieldx.fun/v1

Authentication

All requests require a Bearer token in the Authorization header.

curl -X GET https://api.shieldx.fun/v1/agents \
  -H "Authorization: Bearer sx_live_abc123..." \
  -H "Content-Type: application/json"

MCP Server

Connect ShieldX to any MCP-compatible AI agent — Claude Desktop, Cursor, or custom implementations. One-line install with automatic tool discovery.

{
  "mcpServers": {
    "shieldx": {
      "command": "npx",
      "args": ["-y", "@shieldx/mcp-server"],
      "env": {
        "SHIELDX_API_KEY": "sx_live_..."
      }
    }
  }
}

Available Tools

SDKs & Libraries

Official, type-safe SDKs for Python, TypeScript, and Go. Built-in retry logic, error handling, and webhook verification.

pip install shieldx

npm i @shieldx/sdk

go get github.com/shieldx/go-sdk

Webhooks

Receive real-time HTTP POST notifications for transactions, approvals, rule triggers, and security events.

Event Types

{
  "id": "evt_abc123",
  "type": "transaction.approved",
  "timestamp": "2026-03-04T12:00:00Z",
  "data": {
    "agent_id": "agt_xyz",
    "amount": "250.00",
    "token": "USDC",
    "recipient": "0x1234...5678",
    "status": "auto_approved",
    "rule_results": [
      {"rule": "per_tx_limit", "passed": true},
      {"rule": "daily_budget", "passed": true},
      {"rule": "whitelist", "passed": true}
    ]
  }
}

Security Model

ShieldX uses a defense-in-depth approach with multiple independent security layers. No single point of failure, no trust assumptions.

Threat Matrix

How ShieldX protects against common attack vectors compared to traditional approaches.

Recovery

Social recovery mechanisms ensure you never lose access to your funds. Designate guardians who can help restore wallet control.

API Endpoints

Complete reference for all available REST API endpoints.

Error Codes

Standard error responses with actionable messages.

Rate Limits

Rate limits are applied per API key. Headers indicate your current usage.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1709564400