Skip to main content

Onchain REST API

Complete reference for all Onchain wire REST endpoints.

Wallets​

POST /onchain/wallets​

Create a new wallet.

curl -X POST http://localhost:3000/onchain/wallets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{"name": "Treasury"}'

Response (201):

{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
  "address": "0x1234...5678",
  "name": "Treasury",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

POST /onchain/wallets/import​

Import an existing wallet.

curl -X POST http://localhost:3000/onchain/wallets/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "privateKey": "0xabc123...",
    "name": "Main Wallet"
  }'

GET /onchain/wallets​

List all wallets.

curl http://localhost:3000/onchain/wallets \
  -H "Authorization: Bearer eyJhbGci..."

Balance​

GET /onchain/balance/:address​

Get native token balance.

curl "http://localhost:3000/onchain/balance/0x1234...5678?chain=ethereum" \
  -H "Authorization: Bearer eyJhbGci..."
ParamTypeDefaultDescription
chainstringdefault chainBlockchain network
tokenstring--ERC-20 token address

Response (200):

{
  "address": "0x1234...5678",
  "balance": "1.500000000000000000",
  "symbol": "ETH",
  "chain": "ethereum"
}

Transactions​

POST /onchain/transactions​

Send a transaction.

curl -X POST http://localhost:3000/onchain/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "0xrecipient...5678",
    "value": "0.1",
    "chain": "ethereum",
    "walletId": "65a1b2c3d4e5f6a7b8c9d0e1"
  }'

GET /onchain/transactions/:hash​

Get transaction status.

curl "http://localhost:3000/onchain/transactions/0xabc123...?chain=ethereum" \
  -H "Authorization: Bearer eyJhbGci..."

GET /onchain/transactions​

List transaction history.

curl "http://localhost:3000/onchain/transactions?walletId=65a1b2c3...&limit=20" \
  -H "Authorization: Bearer eyJhbGci..."

Smart Contracts​

POST /onchain/contracts/read​

Read from a smart contract (no gas required).

curl -X POST http://localhost:3000/onchain/contracts/read \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "abi": "erc20",
    "method": "balanceOf",
    "args": ["0x1234...5678"],
    "chain": "ethereum"
  }'

Response (200):

{
  "result": "1000000000",
  "method": "balanceOf"
}

POST /onchain/contracts/write​

Write to a smart contract (sends a transaction).

curl -X POST http://localhost:3000/onchain/contracts/write \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "abi": "erc20",
    "method": "transfer",
    "args": ["0xrecipient...", "1000000"],
    "chain": "ethereum",
    "walletId": "65a1b2c3d4e5f6a7b8c9d0e1"
  }'

Response (200):

{
  "hash": "0xabc123...",
  "status": "pending",
  "chain": "ethereum"
}

NFTs​

POST /onchain/nft/mint​

Mint an NFT.

curl -X POST http://localhost:3000/onchain/nft/mint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "contractAddress": "0xMyNFT...",
    "to": "0xrecipient...5678",
    "tokenURI": "https://api.myapp.com/metadata/1",
    "chain": "arbitrum",
    "walletId": "65a1b2c3d4e5f6a7b8c9d0e1"
  }'

POST /onchain/nft/transfer​

Transfer an NFT.

curl -X POST http://localhost:3000/onchain/nft/transfer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "contractAddress": "0xMyNFT...",
    "to": "0xrecipient...5678",
    "tokenId": "1",
    "chain": "arbitrum",
    "walletId": "65a1b2c3d4e5f6a7b8c9d0e1"
  }'

GET /onchain/nft/:contractAddress/:tokenId​

Get NFT metadata.

curl "http://localhost:3000/onchain/nft/0xMyNFT.../1?chain=arbitrum" \
  -H "Authorization: Bearer eyJhbGci..."

GET /onchain/nft/:contractAddress/owner/:ownerAddress​

List NFTs owned by an address.

curl "http://localhost:3000/onchain/nft/0xMyNFT.../owner/0x1234...?chain=arbitrum" \
  -H "Authorization: Bearer eyJhbGci..."

Health​

GET /onchain/health​

curl http://localhost:3000/onchain/health

Response (200):

{
  "status": "healthy",
  "chains": {
    "ethereum": { "status": "connected", "blockNumber": 19000000 },
    "arbitrum": { "status": "connected", "blockNumber": 175000000 },
    "base": { "status": "connected", "blockNumber": 8000000 }
  }
}