Skip to main content

​
Authentication

All treasury endpoints require admin authentication via the x-admin-key header. 
curl -H "x-admin-key: your-admin-key" https://api.example.com/treasury/balance/0x...
Treasury operations are sensitive and require proper admin key configuration.

​
Runtime Status

curl -X GET https://api.example.com/treasury/runtime \
  -H "x-admin-key: your-admin-key"
Returns the current Pinion runtime configuration and status. 
{
  "success": true,
  "status": {
    "apiKeyConfigured": true,
    "network": "base",
    "runtimeSpendLimit": "10.00 USDC",
    "spentSoFar": "0.15 USDC",
    "remaining": "9.85 USDC"
  }
}

​
API Key Management

​
Set API Key

curl -X POST https://api.example.com/treasury/api-key \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set",
    "apiKey": "pinion_api_key_here"
  }'
Request Body
​
action
string
required
Action to perform: "set", "clear", or omit for status
​
apiKey
string
Pinion API key (required when action is "set")
{
  "success": true,
  "status": {
    "apiKeyConfigured": true
  }
}

​
Clear API Key

curl -X POST https://api.example.com/treasury/api-key \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "clear"}'

​
Unlimited Plan

​
Purchase Unlimited

curl -X POST https://api.example.com/treasury/unlimited/purchase \
  -H "x-admin-key: your-admin-key"
Purchase Pinion Unlimited plan (removes per-call limits). 
{
  "success": true,
  "data": {
    "apiKey": "pinion_unlimited_...",
    "plan": "unlimited",
    "expiresAt": "2027-03-03T00:00:00Z"
  },
  "paidAmount": "0.00",
  "status": {
    "apiKeyConfigured": true
  }
}

​
Verify Unlimited Key

curl -X POST https://api.example.com/treasury/unlimited/verify \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "pinion_unlimited_..."}'
Request Body
​
apiKey
string
required
Pinion Unlimited API key to verify
{
  "success": true,
  "result": {
    "valid": true,
    "plan": "unlimited",
    "expiresAt": "2027-03-03T00:00:00Z"
  }
}

​
Query Operations

​
Get Balance

curl -X GET https://api.example.com/treasury/balance/0x1234... \
  -H "x-admin-key: your-admin-key"
Path Parameters
​
address
string
required
Ethereum address to query
{
  "success": true,
  "data": {
    "address": "0x1234...",
    "eth": "1.5",
    "usdc": "100.50",
    "tokens": [
      {
        "symbol": "WETH",
        "balance": "0.5",
        "value": "1250.00"
      }
    ]
  },
  "paidAmount": "0.01"
}

​
Get Transaction

curl -X GET https://api.example.com/treasury/tx/0xabc... \
  -H "x-admin-key: your-admin-key"
Path Parameters
​
hash
string
required
Transaction hash (0x…)
{
  "success": true,
  "data": {
    "hash": "0xabc...",
    "blockNumber": 12345678,
    "from": "0x1234...",
    "to": "0x5678...",
    "value": "1.0",
    "gasUsed": "21000",
    "status": "success"
  },
  "paidAmount": "0.01"
}

​
Get Token Price

curl -X GET https://api.example.com/treasury/price/WETH \
  -H "x-admin-key: your-admin-key"
Path Parameters
​
token
string
required
Token symbol (e.g., WETH, USDC, DAI)
{
  "success": true,
  "data": {
    "symbol": "WETH",
    "price": "2500.00",
    "change24h": "+3.5%"
  },
  "paidAmount": "0.01"
}

​
Get Funding Info

curl -X GET https://api.example.com/treasury/fund/0x1234... \
  -H "x-admin-key: your-admin-key"
Returns funding recommendations and faucet availability for an address. Path Parameters
​
address
string
required
Address to check funding options for
{
  "success": true,
  "data": {
    "address": "0x1234...",
    "needsFunding": true,
    "recommendedAmount": "0.1 ETH",
    "faucets": [
      {
        "network": "base-sepolia",
        "url": "https://faucet.base.org"
      }
    ]
  },
  "paidAmount": "0.00"
}

​
Execution Operations

​
Generate Wallet

curl -X POST https://api.example.com/treasury/wallet/generate \
  -H "x-admin-key: your-admin-key"
Generates a new Ethereum wallet (address + private key). 
{
  "success": true,
  "data": {
    "address": "0x9876...",
    "privateKey": "0xabcdef..."
  },
  "paidAmount": "0.01"
}
Store private keys securely. Never expose them in logs or client-side code.

​
Send Tokens

curl -X POST https://api.example.com/treasury/send \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0x1234...",
    "amount": "10.5",
    "token": "USDC",
    "execute": true
  }'
Request Body
​
to
string
required
Recipient address
​
amount
string
required
Amount to send (human-readable, e.g., “10.5”)
​
token
string
required
Token symbol: "ETH" or "USDC"
​
execute
boolean
required
Set to true to execute, false for dry-run
{
  "success": true,
  "data": {
    "to": "0x1234...",
    "amount": "10.5",
    "token": "USDC",
    "estimatedGas": "50000",
    "estimatedFee": "0.001 ETH"
  },
  "paidAmount": "0.01"
}

{
  "success": true,
  "data": {
    "txHash": "0xabc...",
    "to": "0x1234...",
    "amount": "10.5",
    "token": "USDC",
    "status": "pending"
  },
  "paidAmount": "0.02"
}

​
Execute Trade

curl -X POST https://api.example.com/treasury/trade \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "src": "USDC",
    "dst": "WETH",
    "amount": "1000",
    "slippage": 0.5,
    "execute": false
  }'
Request Body
​
src
string
required
Source token symbol (e.g., “USDC”, “ETH”)
​
dst
string
required
Destination token symbol
​
amount
string
required
Amount of source token to trade
​
slippage
number
Maximum slippage percentage (default: 0.5)
​
execute
boolean
required
Set to true to execute, false for quote
{
  "success": true,
  "data": {
    "src": "USDC",
    "dst": "WETH",
    "srcAmount": "1000",
    "dstAmount": "0.4",
    "rate": "2500.00",
    "estimatedGas": "150000",
    "slippage": 0.5
  },
  "paidAmount": "0.01"
}

{
  "success": true,
  "data": {
    "txHash": "0xdef...",
    "src": "USDC",
    "dst": "WETH",
    "srcAmount": "1000",
    "dstAmount": "0.398",
    "status": "pending"
  },
  "paidAmount": "0.02"
}

​
Broadcast Transaction

curl -X POST https://api.example.com/treasury/broadcast \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tx": {
      "to": "0x1234...",
      "data": "0x...",
      "value": "0",
      "gasLimit": "100000"
    }
  }'
Request Body
​
tx
object
required
Transaction object to broadcast
{
  "success": true,
  "data": {
    "txHash": "0xabc...",
    "status": "pending"
  },
  "paidAmount": "0.02"
}

​
AI Treasury Chat

curl -X POST https://api.example.com/treasury/chat \
  -H "x-admin-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is my USDC balance?",
    "history": []
  }'
Natural language interface for treasury operations. Request Body
​
message
string
required
User message/query
​
history
array
Previous conversation messages for context
{
  "success": true,
  "data": {
    "response": "Your USDC balance is 100.50 USDC across all wallets.",
    "actions": [
      {
        "type": "balance_query",
        "result": {"usdc": "100.50"}
      }
    ]
  },
  "paidAmount": "0.05"
}

​
Error Responses

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "Invalid payload. Required: { to, amount, token: 'ETH'|'USDC', execute? }"
}

{
  "success": false,
  "error": "Pinion API key not configured"
}

​
Cost Tracking

All treasury operations include a paidAmount field showing the USDC cost for the Pinion API call:
  • Query operations: ~$0.01 USDC per call
  • Execution operations: ~$0.02 USDC per call
  • AI chat: ~$0.05 USDC per message
Pinion Unlimited plan removes per-call costs for high-volume usage.

Build docs developers (and LLMs) love

Get started for freeTalk to us