API Reference

GenesisPad API

Integrate trading bots, analytics dashboards, and applications with GenesisPad on Robinhood Chain. All endpoints return JSON. ETH values in Ether (not Wei). Timestamps are ISO 8601.

Introduction

The GenesisPad API lets you query token launches, trades, chart data, platform metrics, and community chat.

Base URLhttps://api.genesispad.app/api

Trading Bot Integration

To buy and sell tokens, your bot sends transactions directly to the GenesisPad contract on Robinhood Chain. Use the REST API for token discovery and price data; all trades execute on-chain.

Network (Mainnet)

Chain	Robinhood Chain
Chain ID	4663
RPC URL	`https://rpc.mainnet.chain.robinhood.com`
Explorer	`https://robinhoodchain.blockscout.com`

Mainnet Contract Addresses

GenesisPad (Factory)	0xC3Fd21A9EA804FE02Bf3e932d9ac33A66f043eCd
GenesisLocker	0x0372a1AE860CDc9357ac6bc8e9F97856b37B80Ed
Create2Factory	0x17dA64D619235F5FD708258615F6a08CBca6AA94
GenesisToken	0x9589A606fD751760b238e0a05fBA695Fb5B202d9
WETH	0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
Uniswap V2 Router	0x89e5db8b5aa49aa85ac63f691524311aeb649eba
Uniswap V2 Factory	0x8bceaa40b9acdfaedf85adf4ff01f5ad6517937f
Owner / Revenue Recipient	0x8CFa84924011b19765136Baea669AC81FE8bB561

Source: production deployment manifest and on-chain verification.

Smart Contract Functions

These signatures come from the genesisPadAbi in the project source. All trades go through the GenesisPad factory at the address above.

payablebuy(address tok)

Buy tokens by sending ETH with the call. The contract calculates output via the bonding curve. Emits a Trade event.

// Send 1 ETH to buy tokens
const tx = await wallet.sendTransaction({
  to: "0xC3Fd21A9EA804FE02Bf3e932d9ac33A66f043eCd",
  data: encodeFunctionData("buy", [tokenAddress]),
  value: parseEther("1.0"),
});

writesell(address tok, uint256 amt)

Sell tokens. Amount is in token decimal units (usually 18 decimals). Tokens must be approved to GenesisPad first. Emits a Trade event.

// Step 1: approve
await tokenContract.approve(
  "0xC3Fd21A9EA804FE02Bf3e932d9ac33A66f043eCd",
  sellAmount
);

// Step 2: sell
const tx = await wallet.sendTransaction({
  to: "0xC3Fd21A9EA804FE02Bf3e932d9ac33A66f043eCd",
  data: encodeFunctionData("sell", [tokenAddress, sellAmount]),
});

readgetAmountOut(address tok, uint256 amountIn, bool isBuy) → uint256

Calculate expected output. Use isBuy=true for buy estimation, isBuy=false for sell estimation. Call before every trade.

// Estimate tokens for 1 ETH buy
const out = await contract.read.getAmountOut(
  tokenAddress,
  parseEther("1.0"),
  true
);
// out is in token units (18 decimals)

readdata(address _tokenAddr) → tuple

Full token state: creator, tradingStarted, listed (graduated), bonding reserves, tax rates, whitelist status, max wallet limit.

// Output indices:
// [0]  creator         [7]  ethRaised
// [1]  tradingStarted  [8]  tokensSold
// [2]  listed          [9]  virtualEthReserve
// [3]  whitelistOnly   [10] virtualTokenReserve
// [4]  lockLp          [11] k
// [5]  wlCount         [12] feeCollected
// [6]  totalSupply     [13] taxOnGnsBps

readgetMetrics() → tuple

Platform metrics: total volume (ETH), total fees, tokens launched/listed, dev rewards, unique traders, fee settings, creation fee.

// Key indices:
// [0]  totalVolumeEth   [8]  uniqueTraderCount  [19] listingMilestonePct
// [1]  totalFeesEth     [9]  tradeFeeBps        [21] creationFeeEth
// [2]  totalLaunched    [6]  totalDevRewardEth
// [3]  totalListed

Events (Real-Time Monitoring)

Both events are emitted by the GenesisPad factory contract. Subscribe via eth_getLogs or a WebSocket provider.

Trade(address indexed user, address indexed token, bool buy, uint256 inAmt, uint256 outAmt)

Emitted on every buy/sell. Buy: inAmt = ETH sent (Wei), outAmt = tokens received. Sell: inAmt = tokens sold, outAmt = ETH received.

TokenDeployed(address indexed token, address creator, string myIndex)

Emitted when a new token is created. Listen to discover new tokens in real time.

Buy Flow

Use GET /api/tokens to discover tokens and get their tokenAddress.
Call contract.data(tokenAddress) to verify trading has started (index 1 is true) and check reserves.
Call contract.getAmountOut(tokenAddress, ethAmount, true) to estimate tokens received for your ETH.
Send a tx to contract.buy(tokenAddress) with your ETH as msg.value.
Listen for Trade event to confirm the fill.

Sell Flow

Approve GenesisPad to spend your tokens: tokenContract.approve(genesisPadAddress, amount).
Call contract.getAmountOut(tokenAddress, tokenAmount, false) to estimate ETH received.
Call contract.sell(tokenAddress, amount). Amount is in token decimal units.
Listen for Trade event to confirm.

Example (viem)

import { createPublicClient, http, parseEther, formatEther } from "viem";

const GENESIS_PAD = "0xC3Fd21A9EA804FE02Bf3e932d9ac33A66f043eCd";
const RPC = "https://rpc.mainnet.chain.robinhood.com";
const API = "https://api.genesispad.app/api";

const client = createPublicClient({
  chain: {
    id: 4663,
    name: "Robinhood Chain",
    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  },
  transport: http(RPC),
});

// 1. Discover tokens via REST
const tokens = await fetch(API + "/tokens?limit=50").then(r => r.json());
const token = tokens.find(t => t.symbol === "MYTOKEN");

// 2. Check on-chain state
const data = await client.readContract({
  address: GENESIS_PAD,
  abi: [...],
  functionName: "data",
  args: [token.tokenAddress],
});
if (!data[1]) throw new Error("Trading not started");

// 3. Estimate
const out = await client.readContract({
  address: GENESIS_PAD,
  abi: [...],
  functionName: "getAmountOut",
  args: [token.tokenAddress, parseEther("1.0"), true],
});
console.log("Est. tokens:", formatEther(out));

// 4. Execute buy
const hash = await walletClient.sendTransaction({
  to: GENESIS_PAD,
  data: encodeFunctionData("buy", [token.tokenAddress]),
  value: parseEther("1.0"),
});
await client.waitForTransactionReceipt({ hash });

Common Query Parameters

List endpoints accept these optional query parameters for pagination, sorting, and filtering.

Parameter	Type	Default	Description
page	int	1	Page number (1-indexed)
limit	int	30	Results per page (max 100)
sort	string[]	[ "updatedAt" ]	Sort fields, e.g. createdAt:DESC
include	string[]	—	Related entities, e.g. include=image
search	string	—	Generic search string

Endpoints

All endpoints are prefixed with https://api.genesispad.app/api. For example: https://api.genesispad.app/api/tokens.

Tokens

List, find, and manage token launches.

GET/api/tokens

List tokens with pagination and filtering by name, symbol, tokenAddress, tokenCreator. Optional searchTerm enum: address, creator, name, all.

Parameter	Type	Description
name	string[]	Filter by name(s)
symbol	string[]	Filter by symbol(s)
tokenAddress	string[]	Filter by contract address
tokenCreator	string[]	Filter by creator wallet
searchTerm	enum	address \| creator \| name \| all

Example Response

[
  {
    "name": "MyToken",
    "symbol": "MTK",
    "tokenAddress": "0x...",
    "tokenCreator": "0x...",
    "supply": "1000000000",
    "chainId": 4663,
    "chainName": "Robinhood Chain",
    "website": "https://...",
    "description": "...",
    "twitter": "https://x.com/...",
    "telegram": "https://t.me/...",
    "transactionHash": "0x...",
    "createdAt": "2025-06-01T00:00:00.000Z",
    "image": { "id": "uuid", "path": "uploads/logo.png", "mimetype": "image/png" }
  }
]

GET/api/token

Find a single token by address, name, or symbol.

Parameter	Type	Description
tokenAddress	string	Contract address
name	string	Token name
symbol	string	Token symbol

Example Response

{ "name": "MyToken", "symbol": "MTK", "tokenAddress": "0x...", "tokenCreator": "0x...", "supply": "1000000000", "chainId": 4663, "createdAt": "2025-06-01T00:00:00.000Z" }

GET/api/token-all

Get all tokens (unpaginated). Useful for caching the full list.

POST/api/token

Create a token draft. Multipart form with optional logo (max 2 MB).

Request Body

Fields: name, symbol, tokenAddress, tokenCreator, supply, chainId, chainName, transactionHash, verifyparameter, identifier. Optional: website, description, twitter, telegram, tokenVersion, expiresAt, file (logo).

PATCH/api/update-token/:id

Update token details (website, socials, description, logo). Wallet field required.

Parameter	Type	Description
id	string	Token UUID

GET/api/token-onchain

Fetch on-chain token metadata via RPC (name, symbol, supply, creator). Requires tokenAddress.

Parameter	Type	Description
tokenAddress	string	Required. Contract address.

Example Response

{ "name": "MyToken", "symbol": "MTK", "tokenAddress": "0x...", "tokenCreator": "0x...", "supply": "1000000000", "chainId": 4663, "chainName": "Robinhood Chain" }

GET/api/uploads/:image

Get a token's uploaded logo image by filename.

Trades & Transactions

On-chain trade history for any token.

GET/api/transaction/:tokenAddress

Get all trades for a token (buy/sell events).

Parameter	Type	Description
tokenAddress	string	Required. Contract address.

Example Response

[
  {
    "tokenAddress": "0x...",
    "type": "buy",
    "ethAmount": 0.5,
    "tokenAmount": 100000,
    "timestamp": "2025-06-01T00:00:00.000Z",
    "txnHash": "0x...",
    "wallet": "0x..."
  }
]

GET/api/transactions

List all trades with filtering by token, type (buy/sell), wallet, txnHash, ethAmount range, timestamp range.

Parameter	Type	Description
tokenAddress	string[]	Filter by token(s)
type	string[]	buy \| sell
wallet	string[]	Filter by trader wallet
txnHash	string[]	Filter by transaction hash
ethAmount	number[]	ETH amount range
timestamp	string[]	ISO date range

GET/api/trading-onchain

Fallback: fetch on-chain trade logs via RPC when DB has no cached data.

Parameter	Type	Description
tokenAddress	string	Required.
resolution	string	1m \| 5m \| 15m \| 1h \| 4h \| 1d (default: 15m)

Charts & Statistics

OHLC candles, volume, and price stats for building charts.

GET/api/ohlc

OHLC candles for charting. Not rate-limited.

Parameter	Type	Description
tokenAddress	string	Required. Contract address.
resolution	string	1m \| 5m \| 15m \| 1h \| 4h \| 1d (default: 15m)
period	string	Lookback period (default: 30d)

Example Response

[
  {
    "time": 1717200000,
    "open": 0.00005,
    "high": 0.00006,
    "low": 0.00004,
    "close": 0.000055,
    "volume": 1.23
  }
]

GET/api/stats

Token statistics: volume, trades, priceChange, high, low, current, period.

Parameter	Type	Description
tokenAddress	string	Required.
period	string	24h (default)

Example Response

{ "volume": 1.5, "trades": 42, "priceChange": 15.3, "high": 0.00008, "low": 0.00004, "current": 0.000055, "period": "24h" }

GET/api/volume/:tokenAddress

24-hour trading volume for a token.

Parameter	Type	Description
tokenAddress	string	Required.

GET/api/time-frames/:tokenAddress

Available chart timeframes and data span for a token.

Parameter	Type	Description
tokenAddress	string	Required.

Platform

Platform-wide metrics and utility endpoints.

GET/api/aggregate/stats

Platform-wide aggregate statistics (creator tax, platform fees).

Example Response

{ "totalCreatorTaxEth": 12.345, "totalPlatformFeeEth": 67.89 }

GET/api/eth-usd

Current ETH/USD price (Coinbase, cached 60s).

Example Response

{ "usd": 3500.50 }

GET/api/health

Server health check.

Community Chat

Read chat messages for token communities.

GET/api/community-chats

List chat messages for a token community. Filter by groupId (token address) or userId (wallet).

Parameter	Type	Description
groupId	string[]	Filter by token address(es)
userId	string[]	Filter by user wallet(s)

Example Response

[
  {
    "id": "uuid",
    "userId": "0x...",
    "text": "Hello!",
    "groupId": "0x...",
    "createdAt": "2025-06-01T00:00:00.000Z"
  }
]

GET/api/message-count

Get tokens with 50+ messages since a timestamp.

Parameter	Type	Description
timestamp	string	Required. ISO 8601.

GET/api/message-count/:groupId

Message count for a specific token's chat.

Parameter	Type	Description
groupId	string	Token contract address

Users

User profile and balance tracking.

GET/api/user

Find a user by wallet or username.

Parameter	Type	Description
wallet	string	Wallet address
username	string	Username

Example Response

{ "id": "uuid", "username": "alice", "wallet": "0x...", "currentBalance": "0" }

POST/api/user

Create a new user profile.

Request Body

{ "wallet": "0x...", "username": "alice" }

POST/api/track-balance

Record a user's current wallet balance for tracking.

Request Body

{ "wallet": "0x...", "currentBalance": "1000000000000000000" }

Rate Limits

30 requests per 60 seconds globally. The /api/ohlc endpoint is exempt from rate limiting.

Errors

Standard HTTP status codes are used. Error responses include a JSON body with message details.