plugin-gblin

ElizaOS plugin — gasless treasury management for AI agents on Base mainnet.

Park SURPLUS capital into the GBLIN MEV-protected index (cbBTC / WETH / USDC) — managed crypto exposure with capped drawdown, not a USDC substitute — JIT-swap back to USDC to pay x402 invoices, and monitor treasury health — all from inside your ElizaOS agent.

What it does

| Action | Trigger phrases | Cost | |---|---|---| | CHECK_GBLIN_TREASURY_HEALTH | "check my treasury", "wallet status" | $0.002 USDC | | INVEST_IDLE_USDC_GBLIN | "park USDC in GBLIN", "buy GBLIN", "invest 10 USDC" | $0.002 USDC | | RESCUE_USDC_FROM_GBLIN | "need USDC", "sell GBLIN", "JIT swap", "pay invoice" | $0.005 USDC | | GET_GBLIN_RISK_ATTESTATION | "get a risk attestation", "prove you checked risk", "risk receipt" | $0.003 USDC |

The Provider (GBLIN_TREASURY_CONTEXT) injects live NAV, basket weights, and Crash Shield status into every agent loop ($0.001 USDC per call).

All payments are gasless for the agent: the Coinbase CDP facilitator pays on-chain gas; the agent only signs an EIP-3009 transferWithAuthorization.

Install

# with npm
npm install plugin-gblin

# with bun (elizaos default)
bun add plugin-gblin

Or via the ElizaOS CLI:

elizaos plugins add gblin

Configuration

Add to your agent's .env:

# Required
EVM_PRIVATE_KEY=0x_your_agent_hot_wallet_private_key

# Optional — override defaults
GBLIN_BASE_URL=https://gblin.digital
GBLIN_RPC_URL=https://base-rpc.publicnode.com

Security: use a dedicated hot wallet for the agent with only the USDC/GBLIN it needs. Never use a founder or treasury wallet here. The maximum a malicious endpoint could drain in one run is $0.005 USDC.

Add to your character

// character.ts
import { type Character } from "@elizaos/core";

export const character: Character = {
  name: "TreasuryAgent",
  plugins: [
    "@elizaos/plugin-sql",
    "@elizaos/plugin-bootstrap",
    // Add GBLIN only if private key is set
    ...(process.env.EVM_PRIVATE_KEY?.trim() ? ["plugin-gblin"] : []),
  ],
  // ...
};

Or in character.json:

{
  "name": "TreasuryAgent",
  "plugins": ["plugin-gblin"],
  "settings": {
    "secrets": {
      "EVM_PRIVATE_KEY": "0x..."
    }
  }
}

How it works

Agent LLM decides "I have surplus USDC"
  ↓
triggers INVEST_IDLE_USDC_GBLIN action
  ↓
plugin sends GET /api/x402/invest?usdc=10&wallet=0x... (preflight → 402)
  ↓
plugin signs EIP-3009 transferWithAuthorization ($0.002 USDC)
  ↓
plugin retries with PAYMENT-SIGNATURE header
  ↓
GBLIN API returns {steps: [{target, calldata} × 4]}
  ↓
plugin broadcasts step 1 (approve USDC→SwapRouter02) → waits confirmation
  ↓
plugin broadcasts step 2 (swap USDC→WETH) → waits confirmation
  ↓
plugin broadcasts step 3 (approve WETH→GBLIN) → waits confirmation
  ↓
plugin broadcasts step 4 (buyGBLINWithToken) → waits confirmation
  ↓
callback: "✅ Invested $10 USDC → GBLIN. tx: 0xab12..."

Endpoints consumed

All calls go to https://gblin.digital/api/x402/*. Each is a paid x402 v2 endpoint on Base mainnet (chain id 8453, USDC 0x8335...).

| Path | Price | Returns | |---|---|---| | GET /api/x402/treasury-state | $0.001 | NAV, basket, Crash Shield | | GET /api/x402/health?wallet= | $0.002 | balances, gas runway, recommendation | | GET /api/x402/invest?usdc=&wallet= | $0.002 | 4-step calldata (SwapRouter02) | | GET /api/x402/jit?usdc=&wallet= | $0.005 | atomic swap calldata |

Discovery manifest: gblin.digital/api/x402/llms.txt

Protocol

• Contract: 0x36C81d7E1966310F305eA637e761Cf77F90852f0 (Base mainnet)
• Owner: 48h Timelock — every parameter change takes 48 hours on-chain
• Basket: 45% cbBTC + 45% WETH + 10% USDC (rebalances with on-chain Crash Shield)
• MCP Server: @gblin-protocol/mcp-server — free alternative for Claude Desktop / Cursor

Discovery & Ecosystem Integration

GBLIN is integrated across the AI agent ecosystem:

• Base MCP Plugin: PR #56 on base/skills — official Base MCP integration (in review)
• x402 Manifest: https://gblin.digital/.well-known/x402 — paid endpoints discovery
• LLM Discovery: https://gblin.digital/api/x402/llms.txt — free protocol summary
• MCP Server: https://github.com/gblinproject/GBLIN-MCP — same operations via Model Context Protocol

This ElizaOS plugin uses GBLIN's x402 endpoints under the hood. The 4-step atomic batch (approve USDC → swap WETH → approve WETH → buy GBLIN) is fully tested on Base mainnet.

Live Test Proof

Action INVEST_IDLE_USDC_GBLIN tested with real $2 USDC on Base mainnet — 4/4 transactions confirmed.

Wallet tested: 0xd15Ca75fF73AA5173c28bd82FFf302204CF6c6D9

| Step | Description | Transaction | |------|-------------|-------------| | 1 | Approve USDC → SwapRouter02 | 0x83d1e08b... | | 2 | Swap USDC → WETH via exactInputSingle | 0x5bf37e22... | | 3 | Approve WETH → GBLIN contract | 0x4e26cc49... | | 4 | Buy GBLIN with WETH | 0x3d1084f6... |

Treasury health post-invest:

• GBLIN: 0.001074 ($2.14)
• USDC: $0.085
• ETH: 0.001476 ($3.04)
• Total wallet: $5.26

Security

Every transaction the GBLIN API returns is validated before it is signed or broadcast, so a compromised or man-in-the-middled endpoint cannot drain the agent's hot wallet:

• Target allowlist — a broadcast tx may only address GBLIN, USDC, WETH, or Uniswap SwapRouter02 on Base (extend with GBLIN_TX_ALLOWLIST).
• Native-value cap — refuses any ETH-carrying tx by default (GBLIN_MAX_TX_VALUE_WEI).
• Approve hardening — an approve() must target an allowlisted spender and must not be unlimited (max-uint) unless GBLIN_ALLOW_UNLIMITED_APPROVAL=true.
• x402 payment cap — every paid request is limited to USDC-on-Base at or below a per-call ceiling (GBLIN_MAX_X402_USDC, default 0.01), optionally to an expected GBLIN_X402_PAYTO; the client refuses to sign anything a server advertises above policy.
• Opt-in recurring charges — the paid treasury-context provider is off unless GBLIN_TREASURY_PROVIDER_ENABLED=true.

Run the guardrail test suite with bun test — see src/security.test.ts.

License

MIT © GBLIN Protocol