coinrailz

v1.1.0

Published

a month ago

Official SDK for Coin Railz - 66 x402 micropayment services for AI agents including NASA satellite data, trading signals, prediction market arbitrage, and IoT/DePIN.

Coin Railz SDK

Official JavaScript/TypeScript SDK for Coin Railz LLC - x402 micropayment-enabled crypto microservices for AI agents.

Features

🚀 66 Microservices - NASA satellite data, trading intelligence, prediction markets, AI inference, and IoT/DePIN
💳 Simple API Key Auth - No account or blockchain wallet required to start
📦 TypeScript First - Full type definitions included
⚡ Zero Dependencies - Lightweight and fast, uses native fetch
🤖 Built for AI Agents - Native x402 micropayment support for autonomous integration
💰 Yield-While-Trading - Earn USDC yield (Kamino/Aave) while your agent operates
🌍 NASA/ESA Earth Data - Real-time satellite intelligence at $0.15-$0.25/call

Installation

npm install coinrailz

Quick Start (No API Key Required!)

import { CoinRailzClient } from 'coinrailz';

// Zero-config start - works without API key for free services!
const client = new CoinRailzClient();

// FREE: Get gas prices across chains
const gas = await client.gasPriceOracle({ chain: 'base' });
console.log('Gas prices:', gas.data);

// FREE: Get token metadata
const token = await client.tokenMetadata({
  chain: 'base',
  address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
});
console.log('Token:', token.data);

// Paid services auto-fetch a demo key with $1 trial credits!
const signals = await client.tradeSignals({ token: 'ETH' });
console.log('Signal:', signals.data?.signal, 'Confidence:', signals.data?.confidence);

With API Key (Production)

import { CoinRailzClient } from 'coinrailz';

const client = new CoinRailzClient({
  apiKey: process.env.COINRAILZ_API_KEY,
});

// All 66 services available with full credits
const signals = await client.tradeSignals({ token: 'ETH' });

Create an Agent Wallet (Most Valuable Service)

import { CoinRailzClient } from 'coinrailz';

const client = new CoinRailzClient({
  apiKey: process.env.COINRAILZ_API_KEY!,
});

// Create a USDC wallet on Base for your AI agent ($0.50 per wallet)
const wallet = await client.createAgentWallet({
  label: 'my-trading-bot-wallet'
});

if (wallet.success) {
  console.log('Wallet Address:', wallet.data.address);
  console.log('Chain:', wallet.data.chain); // 'base'
  console.log('Wallet ID:', wallet.data.walletId);
  // Store walletId securely for future operations
}

Trading Bot Example

import { CoinRailzClient } from 'coinrailz';

const client = new CoinRailzClient({
  apiKey: process.env.COINRAILZ_API_KEY!,
});

async function runTradingBot() {
  // 1. Check gas before trading
  const gas = await client.gasPriceOracle({ chain: 'base' });
  if (gas.data.gasPrice > 50) {
    console.log('Gas too high, waiting...');
    return;
  }

  // 2. Get AI trading signal
  const signal = await client.tradeSignals({ token: 'ETH' });
  console.log('Signal:', signal.data?.signal); // 'buy', 'sell', or 'hold'
  console.log('Confidence:', signal.data?.confidence);

  // 3. Check whale activity
  const whales = await client.whaleAlerts({ chain: 'ethereum' });
  console.log('Recent whale moves:', whales.data?.alerts?.length);

  // 4. Execute based on signals...
}

runTradingBot();

More examples: Visit coinrailz.com/quickstart for complete runnable examples

Get Your API Key

Instant API Key - Pay $1 (USDC/USDT on Base or Solana) and get your API key immediately. No account required!

Visit coinrailz.com/api-keys
Send $1 to the platform wallet
Verify your transaction and receive your key + $5 starter credits

Key Persistence: Your API key is permanent and works across ALL Coin Railz services. One key = unlimited access (credits are deducted per use). You can top up credits anytime with the same key.

Available Services

🛰️ Satellite Intelligence (NASA & ESA)

satelliteEarthdata() - NASA Earthdata gateway (1B+ datasets)
weatherImagery() - Real-time NASA GIBS satellite weather imagery
floodDetection() - ESA Sentinel-1 SAR flood mapping
fireAlerts() - NASA FIRMS active fire detection

📈 Trading & Market Intelligence

tradeSignals() - AI-powered buy/sell/hold signals
predictionMarketSpread() - [NEW] Arb scanner for Polymarket/Kalshi
whaleAlerts() - Large transaction monitoring ($0.35)
gasPriceOracle() - FREE tier gas prices across 7+ chains

🤖 AI & Execution

aiInference() - Pay-per-call GPT on Base ($0.05)
createAgentWallet() - Instant USDC wallet on Base
seamlessChainBridge() - Automated cross-chain routing
verifiedAgentIdentity() - On-chain agent verification (ERC-8004)

📟 IoT & DePIN

weatherStationData() - Global weather station sensor readings
fleetTelematics() - GPS and vehicle behavior data
iotDeviceStream() - Real-time machine data streams

⚖️ Risk, Banking & Real Estate

walletRisk() - ML-powered wallet risk scoring
complianceCheck() - Regulatory AML/KYC checks
propertyValuation() - AI-driven real estate valuation

See the full 66-service catalog at coinrailz.com/x402/catalog

Generic Call

// Call any service by name
const result = await client.call('custom-service', { param: 'value' });

Get Service Catalog

const catalog = await client.getCatalog();
console.log(`${catalog.data?.totalServices} services available`);

Response Format

All methods return a ServiceResponse<T>:

interface ServiceResponse<T> {
  success: boolean;     // true if request succeeded
  data?: T;             // typed response data
  status: number;       // HTTP status code
  error?: string;       // error message if failed
  raw?: unknown;        // raw JSON response
}

Configuration

const client = new CoinRailzClient({
  apiKey: 'your-api-key',           // Required
  baseUrl: 'https://coinrailz.com', // Optional, defaults to production
  timeoutMs: 30000,                 // Optional, request timeout
});

Error Handling

const result = await client.tradeSignals({ token: 'ETH' });

if (!result.success) {
  console.error('Error:', result.error);
  console.error('Status:', result.status);
  return;
}

console.log('Signal:', result.data?.signal);

Supported Chains

Ethereum
Base
Polygon
Arbitrum
Optimism
BSC (BNB Chain)
PulseChain

Payment Methods

1. Prepaid Credits (Recommended for SDK users)

Purchase credits with credit card (Stripe) or USDC, then use your API key:

const client = new CoinRailzClient({ apiKey: 'your-api-key' });

2. x402 Protocol (Direct USDC payments)

For agents with wallets, pay per request with USDC on Base Chain via HTTP 402:

No API key needed
Autonomous agent compatible
See x402.io for protocol details

Pricing

Services range from $0.10 to $5.00 per call. Free tier available for gas-price-oracle and token-metadata.

See full pricing at coinrailz.com/x402/catalog

License

MIT