ai-oracle-query

name: ai-oracle-query description: "Directly query the APRO AI Oracle Ticker API to fetch live cryptocurrency data — prices, categories, and OHLCV candlestick charts. No code generation needed; the agent calls the API and returns results immediately. Use this skill whenever the user asks for real-time crypto prices, market data, coin categories, price history, candlestick data, or anything related to querying crypto market information from the APRO Oracle. Also triggers on 'check BTC price', 'show me ETH chart', 'what coins are in DeFi category', 'crypto market data', etc." allowed-tools: Read, Bash

APRO AI Oracle Ticker — Live Query

This skill lets you call the APRO AI Oracle Ticker API directly and return data to the user. No code generation — just HTTP requests and formatted results.

Authentication

API calls require two headers: X-API-KEY and X-API-SECRET.

Resolution order (try each in sequence, use the first that works):

1. Environment variables: Check for APRO_API_KEY and APRO_API_SECRET

   echo "${APRO_API_KEY:-NOT_SET}" && echo "${APRO_API_SECRET:-NOT_SET}"
   

2. Ask the user: If either is NOT_SET, ask the user to provide their API key and secret before proceeding. Do not make API calls without valid credentials.

Once obtained, store them in shell variables for the session:

API_KEY="<value>"
API_SECRET="<value>"

API Base

https://api-ai-oracle.apro.com

CRITICAL: Parameter Naming

This API uses full cryptocurrency names (e.g., "Bitcoin", "Ethereum"), NOT ticker symbols like "BTC" or "ETH". When a user says "BTC price", you must translate to name=Bitcoin. Common mappings:

If unsure of the full name, call currency/support with restricted=relaxed first to verify and resolve the name.

Available Endpoints

There are 6 endpoints. Read the user's request and pick the right one(s).

1. List Currencies — GET /v2/ticker/currencies/list

When to use: User asks what coins are available, or you need to look up the full name for a symbol.

Parameters:

Call pattern:

curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currencies/list?page=1&size=20" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}"

Response data: Direct JSON array of {name, symbol, keywords, support_providers} (data is the array itself, not {currencies: [...]})

2. Check Currency Support — GET /v2/ticker/currency/support

When to use: User asks if a specific coin is supported, or you need to verify a coin exists before querying price/OHLCV.

Parameters:

Call pattern:

curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currency/support?name=Bitcoin&restricted=relaxed" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}"

Response data fields: {name, symbol, keywords, support_providers}

3. Get Price — GET /v2/ticker/currency/price

When to use: User asks for current price, or price data for a coin.

Parameters:

Call pattern:

curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currency/price?name=Bitcoin&quotation=USD&type=median" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}"

Response data fields: {name, symbol, quotes, quotes_symbol, price, report_type, timestamp, signature[], prices[]}

The prices array contains individual provider quotes: {name, symbol, quotes, quotes_symbol, price, provider_name, direct_price, last_updated}.

Note: quotes returns the full currency name (e.g., "United States Dollar"), and quotes_symbol returns the code (e.g., "USD").

4. List Categories — GET /v2/ticker/currency/category/list

When to use: User asks what coin categories exist, or wants to browse categories.

Parameters: None.

Call pattern:

curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currency/category/list" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}"

Response data: Direct JSON array of {name, title, description} (data is the array itself, not {categories: [...]})

5. Get Coins by Category — GET /v2/ticker/currency/category/coins

When to use: User asks which coins belong to a category (e.g., "show me DeFi coins").

Parameters:

IMPORTANT — Two-step process (ALWAYS required):

The category parameter takes the name field from the category/list response. You must always call endpoint 4 (category/list) first, match the user's input against the returned entries, then use the exact name field value as the category parameter.

Example flow:

1. User says "show me Meme coins"
2. Call category/list → find entry {"name": "Memes", "title": "Memes", ...}
3. Use category=Memes (the exact name field value)

Call pattern:

# Step 1: Get category list and find the matching category name
CATEGORIES=$(curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currency/category/list" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}")
# Find category name by matching user input (case-insensitive)
CATEGORY=$(echo "$CATEGORIES" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin).get('data',[]) if 'memes' in c.get('name','').lower()]")

# Step 2: Query coins with the resolved category
curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currency/category/coins?category=${CATEGORY}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}"

Response data: Direct JSON array of {name, symbol, ...} (data is the array itself)

6. Get OHLCV — GET /v2/ticker/currency/ohlcv

When to use: User asks for price history, candlestick data, charts, or historical data for a coin.

Parameters:

IMPORTANT: Timestamps are in milliseconds (not seconds). To convert a date to milliseconds:

# Convert ISO date to Unix milliseconds
START_MS=$(date -d "2025-03-01" +%s)000   # Linux
START_MS=$(date -j -f "%Y-%m-%d" "2025-03-01" +%s)000  # macOS

IMPORTANT: Intervals are "hourly" or "daily", NOT "1h" or "1d".

Call pattern:

# Compute timestamps (e.g., last 7 days)
END_MS=$(date +%s)000
START_MS=$(( $(date +%s) - 7 * 86400 ))000

curl -s -X GET "https://api-ai-oracle.apro.com/v2/ticker/currency/ohlcv?name=Bitcoin&quotation=USD&type=median&interval=daily&start_timestamp=${START_MS}&end_timestamp=${END_MS}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "X-API-SECRET: ${API_SECRET}"

Response data fields: {name, symbol, quotes, quotes_symbol, points[], report_type, signature[], ohlcvs[]}

The response has TWO data sets:

• data.points[] — Aggregated OHLCV: {open, high, low, close, volume, timestamp} (timestamps in seconds)
• data.ohlcvs[] — Per-provider data, each with {name, symbol, provider_name, direct, points[]} where points have {open, high, low, close, timestamp} (no volume)

Note: Query params use milliseconds but response timestamps are in seconds.

Security

• Never log or display API credentials — Do not echo, print, or include API_KEY / API_SECRET values in output shown to the user. Use shell variables only; never hardcode them into commands visible in conversation history.
• HTTPS only — All API calls must use https://. Never downgrade to HTTP.
• No credential persistence — Store credentials in shell variables for the current session only. Do not write them to files, shell history, or environment exports that persist beyond the session.
• Sanitize error output — If an API error response contains request headers or credentials, strip them before displaying to the user.
• Respect rate limits — Do not bypass or aggressively retry on 429 responses beyond the single retry defined in the error handling section.

Environment Check

Before making any API call, verify that curl and python3 are available:

command -v curl >/dev/null 2>&1 || { echo "curl is required but not installed."; }
command -v python3 >/dev/null 2>&1 || { echo "python3 is required but not installed."; }

If either is missing, tell the user what to install:

• curl: macOS/Linux usually pre-installed. Windows: winget install cURL.cURL or install Git for Windows (includes curl).
• python3: macOS: brew install python3 or https://python.org/. Windows: winget install Python.Python.3 or https://python.org/. Linux: sudo apt install python3 / sudo dnf install python3.

Do not proceed until both tools are confirmed available.

Request Execution Rules

1. Always use curl -s to suppress progress bars.
2. Always include both auth headers on every request.
3. Parse response with python3 (pre-installed on macOS/Linux, no extra dependencies). Use jq only if you've confirmed it's available.
4. Translate user symbols to full names: Users will say "BTC" but the API needs "Bitcoin". Always translate before calling. If the coin is NOT in the common mappings table above, you MUST call currency/support?name=<best_guess>&restricted=relaxed first to resolve and verify the exact name before calling price or OHLCV endpoints.
5. Check the response envelope first: The API always returns a JSON envelope. Check .status.code before extracting data. Also guard against non-JSON responses:

   RESPONSE=$(curl -s -w "\n%{http_code}" -X GET "${URL}" \
     -H "X-API-KEY: ${API_KEY}" \
     -H "X-API-SECRET: ${API_SECRET}" \
     --connect-timeout 10 --max-time 30)
   
   # Split response body and HTTP status code
   HTTP_CODE=$(echo "$RESPONSE" | tail -1)
   BODY=$(echo "$RESPONSE" | sed '$d')
   
   # Guard: check if body is valid JSON
   if ! echo "$BODY" | python3 -c "import sys,json; json.load(sys.stdin)" 2>/dev/null; then
     echo "Error: API returned non-JSON response (HTTP $HTTP_CODE)"
     echo "$BODY"
     # Stop here — do not try to parse
   fi
   
   # Check API-level status
   API_CODE=$(echo "$BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',{}).get('code',''))")
   
   if [ "$API_CODE" != "200" ]; then
     API_MSG=$(echo "$BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',{}).get('message','Unknown error'))")
     echo "API Error $API_CODE: $API_MSG"
   else
     echo "$BODY" | python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin).get('data'), indent=2))"
   fi
   

6. Chain calls when needed: When querying coins by category, you must always call the category list endpoint first (category/list), match the user's input against the entries, extract the exact name field value, then call category/coins?category=<name>. Never guess the category value — always look it up first.

Output Formatting

Adapt the output format based on the data volume and user intent:

Small data (≤ 10 items, e.g., price of a few coins)

Present directly in conversation as a readable table or summary. Example:

| Coin | Price (USD) | Report Type | Provider Count |
|------|-------------|-------------|----------------|
| Bitcoin | $67,432.15 | median | 3 providers |

Format numbers for readability: use $, T/B/M suffixes, and 2 decimal places for prices.

Medium data (10-50 items, e.g., coins in a category)

Present a summary + top entries in conversation:

Found 245 coins in the DeFi category. Here are the first 10:
[table of first 10]

Large data (> 50 items or OHLCV series)

Save to a file (CSV or JSON) and provide a link, plus a brief summary:

# Save OHLCV data as CSV — always include header row
echo "timestamp,open,high,low,close,volume" > ohlcv_data.csv
echo "$BODY" | python3 -c "
import sys,json,csv
data = json.load(sys.stdin).get('data',{}).get('points',[])
w = csv.writer(sys.stdout)
for p in data:
    w.writerow([p.get('timestamp',''),p.get('open',''),p.get('high',''),p.get('low',''),p.get('close',''),p.get('volume','')])
" >> ohlcv_data.csv

Then tell the user:

Fetched 90 daily candles for Bitcoin. Here's a summary:
- Range: $62,100 – $71,300
- Latest close: $68,200
[Full data saved to ohlcv_data.csv]

When the user explicitly asks for JSON

Return the raw JSON, pretty-printed with python3 -m json.tool.

Error Handling

Handle errors based on BOTH the HTTP status code (from curl) and the API-level status code (from the JSON envelope):

1. Is the response valid JSON?
   NO  → Report "API returned non-JSON response (HTTP <code>)" and stop
   YES → Continue

2. What is .status.code?
   200 → Extract .data and format output
   400 → Show .status.message, suggest user check parameters
   401 → Tell user: "Authentication failed. Please check your API key and secret."
         Do NOT retry — re-ask user for credentials
   429 → Retry once after 5 seconds. If still 429:
         Tell user: "Rate limit hit. Please wait a moment and try again."
   5xx → Retry once after 3 seconds. If still failing:
         Tell user: "Server error (<code>). The API may be temporarily down."

Complete retry pattern:

call_api() {
  local URL="$1"
  local RESPONSE BODY HTTP_CODE API_CODE

  RESPONSE=$(curl -s -w "\n%{http_code}" -X GET "${URL}" \
    -H "X-API-KEY: ${API_KEY}" \
    -H "X-API-SECRET: ${API_SECRET}" \
    --connect-timeout 10 --max-time 30)

  HTTP_CODE=$(echo "$RESPONSE" | tail -1)
  BODY=$(echo "$RESPONSE" | sed '$d')

  # Non-JSON guard
  if ! echo "$BODY" | python3 -c "import sys,json; json.load(sys.stdin)" 2>/dev/null; then
    echo "ERROR: Non-JSON response (HTTP $HTTP_CODE)"
    return 1
  fi

  API_CODE=$(echo "$BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',{}).get('code',''))")

  # 401: no retry, credential issue
  if [ "$API_CODE" = "401" ]; then
    echo "AUTH_ERROR"
    return 1
  fi

  # 429: retry once after 5s
  if [ "$API_CODE" = "429" ]; then
    sleep 5
    RESPONSE=$(curl -s -w "\n%{http_code}" -X GET "${URL}" \
      -H "X-API-KEY: ${API_KEY}" -H "X-API-SECRET: ${API_SECRET}" \
      --connect-timeout 10 --max-time 30)
    HTTP_CODE=$(echo "$RESPONSE" | tail -1)
    BODY=$(echo "$RESPONSE" | sed '$d')
    API_CODE=$(echo "$BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',{}).get('code',''))")
  fi

  # 5xx: retry once after 3s
  if [ "$API_CODE" -ge 500 ] 2>/dev/null; then
    sleep 3
    RESPONSE=$(curl -s -w "\n%{http_code}" -X GET "${URL}" \
      -H "X-API-KEY: ${API_KEY}" -H "X-API-SECRET: ${API_SECRET}" \
      --connect-timeout 10 --max-time 30)
    HTTP_CODE=$(echo "$RESPONSE" | tail -1)
    BODY=$(echo "$RESPONSE" | sed '$d')
    API_CODE=$(echo "$BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',{}).get('code',''))")
  fi

  # Final check
  if [ "$API_CODE" != "200" ]; then
    echo "$BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',{}).get('message','Unknown error'))"
    return 1
  fi

  echo "$BODY" | python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin).get('data'), indent=2))"
  return 0
}

Interpreting User Requests — Examples