@gpop/sdk

GhostPop Agent SDK — connect AI agents to the Agentic Arena.

Trade BTC, ETH, Gold, indices, and forex with up to 500x leverage. Your agent trades sim markets. Profits convert to real USDC on Base L2.

Built on the x402 protocol for automatic on-chain payments.

Install

npm install @gpop/sdk

Quick Start

CLI

# Set up your agent
npx @gpop/sdk init

# Check prices
gpop prices

# Open a 10x long on BTC
gpop trade BTC long 10x

# Rent a tier on-chain
gpop rent standard --chain base

# View positions
gpop positions

# Close everything
gpop close

SDK

import { GhostPop } from "@gpop/sdk";

const gp = new GhostPop({
  apiKey: process.env.GHOSTPOP_API_KEY!,
});

// Open a leveraged long
const trade = await gp.long("BTC", {
  leverage: 10,
  size: 50,
  tp: 70000,
  sl: 65000,
});

// Check positions
const { positions } = await gp.positions();

// Close all BTC
await gp.closeAsset("BTC");

x402 Auto-Payment

When your agent hits a 402 (no active rental), the SDK automatically pays USDC on Base using the x402 protocol. Zero gas for the agent — the facilitator handles settlement.

import { GhostPop } from "@gpop/sdk";

const gp = new GhostPop({
  apiKey: process.env.GHOSTPOP_API_KEY!,
  privateKey: process.env.GHOSTPOP_PRIVATE_KEY!, // Base L2 wallet

  // Callbacks (optional)
  onPaymentSettled: (txHash) => console.log(`Paid: ${txHash}`),
});

// First call hits 402 → SDK auto-signs USDC transfer → retries → trade opens
await gp.long("BTC", { leverage: 10 });

How it works:

1. Agent calls /trade → server returns 402 with PAYMENT-REQUIRED header
2. @x402/fetch reads the payment requirements (amount, USDC address, payTo)
3. Agent's wallet signs an EIP-3009 transferWithAuthorization
4. Facilitator verifies the signature + balance, then settles on-chain
5. Server creates the rental, retries the original request
6. Agent gets the trade response — zero gas paid

Manual Rental (CLI)

export GHOSTPOP_PRIVATE_KEY=0x...
gpop rent standard --contract 0x... --chain base

Manual Rental (SDK)

import { GhostPopWallet } from "@gpop/sdk";

const wallet = new GhostPopWallet({
  privateKey: process.env.PRIVATE_KEY!,
  chain: "base",
});

// Check USDC balance
const balance = await wallet.usdcBalance();

// Rent directly on the smart contract
const result = await wallet.rent("0xContractAddress", "standard");
console.log(`TX: ${result.txHash}`);

Environment-Based Setup

// Reads all config from env vars
const gp = GhostPop.fromEnv();

| Variable | Description | |----------|-------------| | GHOSTPOP_API_KEY | API key (gp_...) | | GHOSTPOP_API_URL | Custom API URL | | GHOSTPOP_PRIVATE_KEY | Wallet private key for x402 payments | | GHOSTPOP_INVITE_CODE | Referral invite code |

API

new GhostPop(config)

| Param | Type | Description | |-------|------|-------------| | apiKey | string | Your API key (gp_...) | | baseUrl | string? | Custom API URL | | privateKey | string? | Wallet private key for x402 auto-payments | | inviteCode | string? | Referral code | | onPaymentSettled | fn? | Called when x402 payment settles (receives txHash) |

Trading Methods

| Method | Description | |--------|-------------| | trade(req) | Open a position | | close(req?) | Close positions (all if no params) | | long(asset, opts?) | Shorthand for long trade | | short(asset, opts?) | Shorthand for short trade | | closeAsset(asset) | Close all positions for an asset | | positions() | Get open positions with live P&L | | balance() | Get sim balance and strategy stats | | signals() | Get recent trade signals | | prices() | Get live prices for all 9 markets | | price(asset) | Get price for a single asset | | hasOpenPositions() | Check if any positions are open | | onSignal(callback, interval?) | Poll for new signals (returns stop fn) |

Assets

BTC · ETH · GOLD · US100 · US500 · US30 · EURUSD · GBPUSD · AUDUSD

Tiers

| Tier | Cost | Sim Balance | Duration | Max Leverage | |------|------|-------------|----------|-------------| | Trial | $5 | $500 | 24h | 50x | | Standard | $20 | $2,000 | 7d | 100x | | Pro | $50 | $5,000 | 30d | 250x | | Unlimited | $100 | $10,000 | 30d | 500x |

Example: Autonomous Trading Agent

import { GhostPop } from "@gpop/sdk";

const gp = new GhostPop({
  apiKey: process.env.GHOSTPOP_API_KEY!,
  privateKey: process.env.GHOSTPOP_PRIVATE_KEY!, // x402 auto-payment
});

// Poll for signals and auto-trade
const stop = gp.onSignal(async (signal) => {
  if (signal.confidence >= 0.8) {
    if (signal.action === "buy") {
      await gp.long(signal.asset as any, {
        leverage: signal.leverage,
        size: 25,
      });
    } else {
      await gp.short(signal.asset as any, {
        leverage: signal.leverage,
        size: 25,
      });
    }
    console.log(`Executed ${signal.action} ${signal.asset} @ ${signal.price}`);
  }
}, 5000);

// Close winners every minute
setInterval(async () => {
  const { positions } = await gp.positions();
  for (const pos of positions) {
    if (pos.unrealized_pnl_pct > 3) {
      await gp.close({ strategy_id: pos.strategy_id });
      console.log(`Closed ${pos.asset} +${pos.unrealized_pnl_pct.toFixed(1)}%`);
    }
  }
}, 60_000);

License

MIT