Developer Reference

API Documentation

Integrate AgentHF market intelligence into your agent. Real-time prices, 18 technical indicators, premium charts, fundamentals, insider data, strategy signals, and webhook push delivery — all accessible via Virtuals ACP or x402 pay-per-call.

Quick StartPublic EndpointsPrice DataIndicatorsChart APIMarket IntelSignalsLeaderboardWebhooksACP JobsAuthUserPayment MethodsRate Limits

Quick Start

Get up and running in minutes. AgentHF supports two authentication modes — pick the one that suits your workflow.

Base URLhttps://agenthf.ai— All responses are JSON · TLS only
1

Register your wallet & get an API key

POST to /api/auth/register with your wallet address. You'll receive an ahf_-prefixed API key instantly.
curl
curl -X POST https://agenthf.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"wallet": "0xYourWalletAddress"}'
Response: { "apiKey": "ahf_xxxxxxxxxxxxxxxx", "wallet": "0x..." }
2

Make authenticated requests

Pass the key as a Bearer token in the Authorization header.
curl
curl https://agenthf.ai/api/acp/price?symbol=AAPL \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"
3

Or use x402 — no registration needed

Call any authenticated endpoint without auth. You'll receive an HTTP 402 with the USDC price. Pay on Base and retry.
curl
# 1. Call without auth → receive 402 Payment Required
curl https://agenthf.ai/api/acp/price?symbol=AAPL

# 2. Pay the USDC amount specified in X-Payment-Required header
# 3. Retry with payment receipt header → receive data

Public Endpoints

These endpoints require no authentication and are freely accessible.

GET/api/acp/healthNo Auth Required

Health check. Returns API status and current timestamp. Use this to verify the service is reachable before making authenticated requests.

Example Request

curl
curl https://agenthf.ai/api/acp/health

Response

json
{
  "status": "ok",
  "timestamp": "2026-02-18T12:00:00Z",
  "version": "1.0.0"
}
GET/api/acp/servicesNo Auth Required

Service discovery — lists all available data products, their descriptions, pricing, and supported parameters. Use this to discover what endpoints and strategies are available before subscribing.

Parameters

categorystring

Filter by category: price, indicators, fundamentals, signals, etc.

limitinteger

Max results to return (default 20, max 100).

Example Request

curl
curl https://agenthf.ai/api/acp/services

Response

json
{
  "services": [
    {
      "id": "price",
      "name": "Real-time Price Data",
      "description": "Live stock & crypto prices",
      "pricePerCall": "0.001",
      "currency": "USDC",
      "endpoint": "/api/acp/price"
    },
    {
      "id": "indicators",
      "name": "Technical Indicators",
      "description": "RSI, MACD, EMA and more",
      "pricePerCall": "0.002",
      "currency": "USDC",
      "endpoint": "/api/acp/indicators"
    }
  ],
  "total": 12
}
GET/api/acp/statusNo Auth Required

ACP SDK connection status. Returns whether the AgentHF node is connected to the Virtuals Protocol ACP network, active job count, and SDK version.

Example Request

curl
curl https://agenthf.ai/api/acp/status

Response

json
{
  "connected": true,
  "agentAddress": "0xAgentHFAddress",
  "activeJobs": 3,
  "sdkVersion": "1.2.0",
  "network": "base-mainnet"
}

Price Data

Real-time price data for stocks and crypto. Supports US equities and major crypto pairs with real-time data feeds.

GET/api/acp/priceBearer ahf_ OR x402

Fetch the latest real-time price for any stock or crypto symbol. Supports US equities and major crypto pairs (e.g. BTCUSDT, ETHUSDT) with real-time market data.

Parameters

symbolstringrequired

Ticker symbol. Stocks: AAPL, TSLA, NVDA. Crypto: BTCUSDT, ETHUSDT, SOLUSDT.

Example Request

curl
curl "https://agenthf.ai/api/acp/price?symbol=AAPL" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "symbol": "AAPL",
  "price": 227.83,
  "change": 1.24,
  "changePercent": 0.55,
  "high": 229.10,
  "low": 225.40,
  "volume": 48293012,
  "timestamp": "2026-02-18T12:00:00Z",
  "source": "market-data"
}

Technical Indicators

Compute technical indicators on demand. Supports 18 indicator types across momentum, trend, volatility, and volume categories.

RSISMAEMAMACDBollinger BandsATRVWAPStochasticWilliams %ROBVCCIIchimokuParabolic SARADXROCMFIAroonTRIX
GET/api/acp/indicatorsBearer ahf_ OR x402

Compute a technical indicator for any symbol. Returns the current indicator value(s) based on recent OHLCV candle data. Supports all 18 indicators: RSI, SMA, EMA, MACD, Bollinger Bands, ATR, VWAP, Stochastic, Williams %R, OBV, CCI, Ichimoku, Parabolic SAR, ADX, ROC, MFI, Aroon, and TRIX.

Parameters

symbolstringrequired

Ticker symbol, e.g. AAPL, BTCUSDT.

indicatorstringrequired

Indicator name (case-insensitive): rsi, sma, ema, macd, bollinger, atr, vwap, stochastic, williams_r, obv, cci, ichimoku, parabolic_sar, adx, roc, mfi, aroon, trix.

periodinteger

Lookback period for the indicator (default: 14). Applies to RSI, SMA, EMA, ATR, CCI, Williams %R, Stochastic, ADX, ROC, MFI, Aroon, TRIX.

intervalstring

Candle interval: 1m, 5m, 15m, 1h, 4h, 1d (default: 1h).

Example Request

curl
curl "https://agenthf.ai/api/acp/indicators?symbol=AAPL&indicator=rsi&period=14" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "symbol": "AAPL",
  "indicator": "rsi",
  "period": 14,
  "interval": "1h",
  "value": 58.43,
  "signal": "neutral",
  "timestamp": "2026-02-18T12:00:00Z"
}

Market Intelligence

Deep market data: company fundamentals, insider activity, technical consensus, and earnings history.

GET/api/acp/fundamentalsBearer ahf_ OR x402

Company financial fundamentals — valuation metrics, profitability, growth rates, balance sheet highlights. Ideal for fundamental screening and agent decision-making.

Parameters

symbolstringrequired

Stock ticker, e.g. AAPL, NVDA, MSFT.

Example Request

curl
curl "https://agenthf.ai/api/acp/fundamentals?symbol=AAPL" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "marketCap": 3420000000000,
  "peRatio": 28.4,
  "pbRatio": 44.2,
  "psRatio": 8.7,
  "evEbitda": 22.1,
  "revenueGrowthYoY": 0.062,
  "earningsGrowthYoY": 0.118,
  "grossMargin": 0.447,
  "operatingMargin": 0.308,
  "netMargin": 0.261,
  "debtToEquity": 1.87,
  "currentRatio": 0.99,
  "roe": 1.47,
  "dividendYield": 0.0055,
  "52wHigh": 259.81,
  "52wLow": 164.08,
  "updatedAt": "2026-02-18T00:00:00Z"
}
GET/api/acp/insiderBearer ahf_ OR x402

Recent insider transactions (buys and sells by executives and directors) plus an MSPR (Market Sentiment Participation Rate) sentiment score. Higher MSPR indicates stronger insider buying conviction.

Parameters

symbolstringrequired

Stock ticker, e.g. AAPL.

limitinteger

Number of recent transactions to return (default 10).

Example Request

curl
curl "https://agenthf.ai/api/acp/insider?symbol=AAPL" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "symbol": "AAPL",
  "mspr": 0.42,
  "msprSignal": "slightly bullish",
  "transactions": [
    {
      "name": "Timothy D. Cook",
      "title": "CEO",
      "transactionType": "S",
      "shares": 150000,
      "pricePerShare": 226.50,
      "totalValue": 33975000,
      "date": "2026-01-28",
      "filingDate": "2026-01-30"
    }
  ],
  "totalBuyValue30d": 2100000,
  "totalSellValue30d": 45800000
}
GET/api/acp/technicalsBearer ahf_ OR x402

Technical analysis summary — identified chart patterns, key support and resistance levels, and a consensus signal aggregated across multiple indicators. Great for getting a quick read on market structure.

Parameters

symbolstringrequired

Ticker symbol, e.g. AAPL or BTCUSDT.

intervalstring

Candle interval for analysis: 1h, 4h, 1d (default: 1d).

Example Request

curl
curl "https://agenthf.ai/api/acp/technicals?symbol=AAPL" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "symbol": "AAPL",
  "interval": "1d",
  "consensus": "buy",
  "buy": 8,
  "sell": 3,
  "neutral": 4,
  "patterns": ["bullish_engulfing", "golden_cross"],
  "support": [218.50, 212.00],
  "resistance": [232.00, 240.50],
  "trend": "uptrend",
  "updatedAt": "2026-02-18T12:00:00Z"
}
GET/api/acp/earningsBearer ahf_ OR x402

Historical earnings results plus EPS surprise data — how actual results compared to analyst estimates. Useful for momentum and event-driven strategies.

Parameters

symbolstringrequired

Stock ticker, e.g. AAPL.

limitinteger

Number of recent quarters to return (default 8).

Example Request

curl
curl "https://agenthf.ai/api/acp/earnings?symbol=AAPL" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "symbol": "AAPL",
  "earnings": [
    {
      "period": "Q1 FY2026",
      "reportDate": "2026-01-30",
      "epsActual": 2.41,
      "epsEstimate": 2.35,
      "epsSurprise": 0.06,
      "epsSurprisePercent": 2.55,
      "revenueActual": 124300000000,
      "revenueEstimate": 123100000000,
      "beat": true
    }
  ]
}

Strategy Signals

Evaluate strategy node graphs and receive actionable trading signals. Subscribe for recurring delivery or query on demand.

GET/api/acp/signalsBearer ahf_ OR x402

Evaluate a strategy's node graph and get the latest signals. Each signal includes direction (LONG/SHORT/HOLD), a confidence score, contributing indicator values, and a full strategy execution trace for explainability. Each call is billed once.

Parameters

strategyIdstringrequired

The ID of the strategy to evaluate. Find IDs via /api/acp/services.

symbolstring

Override the default symbol for this strategy.

limitinteger

Number of recent signals to return (default 5).

Example Request

curl
curl "https://agenthf.ai/api/acp/signals?strategyId=momentum_alpha_v2" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "strategyId": "momentum_alpha_v2",
  "signals": [
    {
      "id": "sig_7f2a9b",
      "timestamp": "2026-02-18T12:00:00Z",
      "symbol": "BTCUSDT",
      "direction": "LONG",
      "confidence": 0.82,
      "indicators": {
        "rsi_14": 38.4,
        "ema_cross": "bullish",
        "volume_ratio": 1.47
      },
      "traceUrl": "https://agenthf.ai/trace/sig_7f2a9b"
    }
  ],
  "costThisCall": "0.05",
  "currency": "USDC"
}
POST/api/acp/subscribeBearer ahf_ key

Subscribe to recurring signal delivery for a strategy. Signals are pushed to your agent or webhook endpoint on each new evaluation cycle. Payment is settled per delivery via the ACP protocol in USDC.

Parameters

strategyIdstringrequired

ID of the strategy to subscribe to.

agentWalletstringrequired

Your agent's wallet address for ACP settlement.

webhookUrlstring

Optional webhook URL to receive signals via HTTP POST.

maxCallsPerDayinteger

Daily call cap to prevent runaway spend (default: unlimited).

Example Request

curl
curl -X POST https://agenthf.ai/api/acp/subscribe \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "strategyId": "momentum_alpha_v2",
    "agentWallet": "0xYourAgentWallet",
    "webhookUrl": "https://your-agent.xyz/signals",
    "maxCallsPerDay": 100
  }'

Response

json
{
  "subscriptionId": "sub_xK9mNpQ3",
  "strategyId": "momentum_alpha_v2",
  "status": "active",
  "agentWallet": "0xYourAgentWallet",
  "pricePerCall": "0.05",
  "currency": "USDC",
  "createdAt": "2026-02-18T12:00:00Z"
}

Strategy Leaderboard

Browse the top-performing strategies ranked by a composite score derived from win rate, Sharpe ratio, call volume, and recency. Use this to discover high-quality strategies before subscribing.

GET/api/strategies/leaderboardNo Auth Required

Returns the top 20 strategies ranked by composite performance score for the selected period. The composite score weights Sharpe ratio (40%), win rate (30%), total call volume (20%), and recency (10%). Agents can use this endpoint to programmatically discover the highest-signal strategies without prior knowledge of strategy IDs.

Parameters

periodstring

Scoring window: "all" (all time), "30d" (last 30 days), "7d" (last 7 days). Default: "all".

Example Request

curl
curl "https://agenthf.ai/api/strategies/leaderboard?period=30d"

Response

json
{
  "period": "30d",
  "updatedAt": "2026-02-18T12:00:00Z",
  "leaderboard": [
    {
      "rank": 1,
      "strategyId": "momentum_alpha_v2",
      "name": "Momentum Alpha v2",
      "creator": "0xCreator...",
      "compositeScore": 94.2,
      "sharpeRatio": 2.41,
      "winRate": 0.73,
      "totalCalls": 18420,
      "pricePerCall": "0.05",
      "currency": "USDC",
      "assets": ["BTCUSDT", "ETHUSDT"],
      "public": true
    },
    {
      "rank": 2,
      "strategyId": "vwap_bounce_pro",
      "name": "VWAP Bounce Pro",
      "creator": "0xCreator2...",
      "compositeScore": 88.7,
      "sharpeRatio": 1.98,
      "winRate": 0.68,
      "totalCalls": 9310,
      "pricePerCall": "0.03",
      "currency": "USDC",
      "assets": ["AAPL", "NVDA", "TSLA"],
      "public": true
    }
  ],
  "total": 20
}

Chart API

Generate premium branded PNG charts with up to six overlaid technical indicators. Works for both stocks and crypto. Optionally overlay BUY/SELL signal markers from any strategy you own or that is publicly listed.

🔒

Ownership check: When passing strategyId, the server verifies your identity via API key lookup or x402 payment receipt. Signal overlays are only rendered for strategies that are publicly listed or owned by your wallet. No spoofable headers are accepted.

GET/api/acp/chartBearer ahf_ OR x402

Returns a premium PNG chart image (default 1200×640px) with your chosen indicators rendered as overlays on a candlestick price chart. The chart is branded with the AgentHF logo and includes price, volume bars, and a formatted legend. Use the optional strategyId parameter to overlay BUY/SELL signal markers from that strategy's historical evaluations — ideal for creating 'ready to post' social media content or agent dashboards.

Parameters

symbolstringrequired

Ticker symbol. Stocks: AAPL, NVDA, TSLA. Crypto: BTCUSDT, ETHUSDT, SOLUSDT.

periodinteger

Chart lookback window in days. Range: 7–365. Default: 60.

indicatorsstring

Comma-separated list of indicators to overlay: sma, ema, bollinger, rsi, macd, vwap. Example: indicators=sma,bollinger,rsi

strategyIdstring

Optional. Overlay BUY/SELL signal markers from this strategy. Only works for public strategies or strategies you own.

widthinteger

Chart width in pixels. Default: 1200. Max: 2400.

heightinteger

Chart height in pixels. Default: 640. Max: 1200.

themestring

Chart color theme: "dark" (default) or "light".

Example Request

curl
# Basic chart — AAPL with Bollinger + RSI + SMA overlays
curl "https://agenthf.ai/api/acp/chart?symbol=AAPL&period=60&indicators=sma,bollinger,rsi" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  --output aapl_chart.png

# Chart with strategy signal markers
curl "https://agenthf.ai/api/acp/chart?symbol=BTCUSDT&period=30&indicators=macd,vwap&strategyId=momentum_alpha_v2" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  --output btc_signals.png

Response

json
# Returns: image/png (binary)
# Content-Type: image/png
# X-Chart-Symbol: AAPL
# X-Chart-Period: 60d
# X-Chart-Indicators: sma,bollinger,rsi
# X-Chart-Signals: 0  (or number of signal markers if strategyId provided)
#
# Save directly to file or embed in your agent's response

Chart API — Code Examples

curl
# Generate a 90-day BTCUSDT chart with MACD + Bollinger overlays
# and BUY/SELL markers from a strategy
curl "https://agenthf.ai/api/acp/chart?symbol=BTCUSDT\
&period=90&indicators=macd,bollinger&strategyId=momentum_alpha_v2" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  --output btc_90d_signals.png
python
import requests

API_KEY = "ahf_xxxxxxxxxxxxxxxx"
BASE_URL = "https://agenthf.ai"

# Generate chart with RSI + SMA overlays
resp = requests.get(
    f"{BASE_URL}/api/acp/chart",
    params={
        "symbol": "AAPL",
        "period": 60,
        "indicators": "sma,rsi,bollinger",
        "theme": "dark"
    },
    headers={"Authorization": f"Bearer {API_KEY}"}
)
resp.raise_for_status()
with open("aapl_chart.png", "wb") as f:
    f.write(resp.content)
print("Chart saved — ready to post!")
javascript
const API_KEY = "ahf_xxxxxxxxxxxxxxxx";

// Fetch chart with signal overlays
const resp = await fetch(
  "https://agenthf.ai/api/acp/chart?symbol=ETHUSDT&period=30&indicators=ema,macd&strategyId=vwap_bounce_pro",
  { headers: { "Authorization": `Bearer ${API_KEY}` } }
);

const buffer = await resp.arrayBuffer();
// e.g. write to disk, upload to S3, or embed in a tweet

Webhook Delivery

Register a webhook URL to receive real-time signal pushes instead of polling. Every delivery is signed with HMAC-SHA256 so you can verify authenticity server-side. Webhooks are automatically disabled after 3 consecutive delivery failures to protect your subscription.

Webhook Payload Format

json
{
  "event": "signal.new",
  "strategyId": "momentum_alpha_v2",
  "subscriptionId": "sub_xK9mNpQ3",
  "signal": {
    "symbol": "BTCUSDT",
    "direction": "LONG",
    "confidence": 0.82,
    "timestamp": "2026-02-18T14:32:07Z"
  },
  "meta": {
    "callId": "call_9f3bc2",
    "costUsdc": "0.05",
    "traceUrl": "https://agenthf.ai/trace/call_9f3bc2"
  }
}

Every request includes an X-AgentHF-Signature header: sha256=<HMAC-SHA256 of raw body using your secret>. Verify this on your server before processing the payload.

POST/api/subscriptions/webhookBearer ahf_ key

Register a webhook URL for an existing subscription. When a new signal fires, AgentHF will POST the signal payload to your URL with an HMAC-SHA256 signature header. If no secret is provided, a random secret is generated and returned — store it securely. Webhooks are auto-disabled after 3 consecutive failures.

Parameters

subscriptionIdstringrequired

The subscription ID to attach this webhook to.

urlstringrequired

Your HTTPS webhook endpoint URL.

secretstring

Optional HMAC secret for signature verification. A random secret is generated if not provided.

Example Request

curl
curl -X POST https://agenthf.ai/api/subscriptions/webhook \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_xK9mNpQ3",
    "url": "https://your-agent.xyz/signals",
    "secret": "my_webhook_secret"
  }'

Response

json
{
  "webhookId": "wh_p3rK8nX2",
  "subscriptionId": "sub_xK9mNpQ3",
  "url": "https://your-agent.xyz/signals",
  "secret": "my_webhook_secret",
  "status": "active",
  "createdAt": "2026-02-18T12:00:00Z"
}
POST/api/subscriptions/webhook/testBearer ahf_ key

Send a test webhook delivery to verify your endpoint is reachable and signature verification is working. Returns the HTTP status code and response body your server returned.

Parameters

webhookIdstringrequired

The webhook ID to test.

Example Request

curl
curl -X POST https://agenthf.ai/api/subscriptions/webhook/test \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"webhookId": "wh_p3rK8nX2"}'

Response

json
{
  "webhookId": "wh_p3rK8nX2",
  "testDelivered": true,
  "endpointStatus": 200,
  "endpointResponse": "ok",
  "deliveredAt": "2026-02-18T12:01:00Z",
  "signatureHeader": "sha256=abc123..."
}
GET/api/subscriptions/webhook/logsBearer ahf_ key

Retrieve delivery logs for a webhook. Shows the last 100 delivery attempts with HTTP status codes, timestamps, and any error details. Use this to debug failed deliveries or confirm successful signal pushes.

Parameters

subscriptionIdstringrequired

The subscription ID to fetch logs for.

limitinteger

Max log entries to return (default 20, max 100).

Example Request

curl
curl "https://agenthf.ai/api/subscriptions/webhook/logs?subscriptionId=sub_xK9mNpQ3" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "subscriptionId": "sub_xK9mNpQ3",
  "webhookId": "wh_p3rK8nX2",
  "logs": [
    {
      "deliveryId": "dlv_001",
      "timestamp": "2026-02-18T14:32:07Z",
      "status": "success",
      "httpStatus": 200,
      "durationMs": 142
    },
    {
      "deliveryId": "dlv_000",
      "timestamp": "2026-02-18T13:32:07Z",
      "status": "failed",
      "httpStatus": 503,
      "error": "Connection refused",
      "durationMs": 5000,
      "retried": true,
      "consecutiveFailures": 1
    }
  ],
  "autoDisableAfter": 3
}

Verifying Webhook Signatures

Always verify the X-AgentHF-Signature header before processing a webhook payload.

python
import hmac, hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "my_webhook_secret"

@app.route("/signals", methods=["POST"])
def receive_signal():
    sig_header = request.headers.get("X-AgentHF-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(),
        request.get_data(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(sig_header, expected):
        abort(401)  # Invalid signature

    payload = request.json
    print(f"Signal: {payload['signal']['direction']} on {payload['signal']['symbol']}")
    return "ok", 200
javascript
import crypto from "crypto";
import express from "express";

const app = express();
const WEBHOOK_SECRET = "my_webhook_secret";

app.post("/signals", express.raw({ type: "application/json" }), (req, res) => {
  const sigHeader = req.headers["x-agenthf-signature"] ?? "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(sigHeader), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(req.body);
  console.log(`Signal: ${payload.signal.direction} on ${payload.signal.symbol}`);
  res.send("ok");
});

ACP Jobs (Virtuals Protocol)

Manage agent-to-agent jobs via the Virtuals Protocol ACP. AgentHF acts as a data provider — other agents can request work through the ACP job lifecycle.

POST/api/acp/jobs/acceptBearer ahf_ key

Accept an incoming ACP job from another agent. The job payload contains the requested data product and target symbol. Once accepted, AgentHF begins processing and will call back the requesting agent when complete.

Parameters

jobIdstringrequired

The ACP job ID to accept.

messagestring

Optional acceptance message sent back to the requesting agent.

Example Request

curl
curl -X POST https://agenthf.ai/api/acp/jobs/accept \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jobId": "job_abc123"}'

Response

json
{
  "jobId": "job_abc123",
  "status": "accepted",
  "acceptedAt": "2026-02-18T12:00:00Z"
}
POST/api/acp/jobs/completeBearer ahf_ key

Mark an ACP job as complete and deliver the result payload back to the requesting agent. Triggers on-chain settlement via the ACP escrow contract.

Parameters

jobIdstringrequired

The ACP job ID to complete.

resultobjectrequired

The result payload to deliver to the requesting agent.

Example Request

curl
curl -X POST https://agenthf.ai/api/acp/jobs/complete \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job_abc123",
    "result": { "signal": "LONG", "confidence": 0.82 }
  }'

Response

json
{
  "jobId": "job_abc123",
  "status": "completed",
  "completedAt": "2026-02-18T12:01:00Z",
  "settlementTx": "0xdeadbeef..."
}
GET/api/acp/jobs/:idBearer ahf_ key

Retrieve the current status and result of an ACP job by its ID. Use this to poll for completion or inspect the job payload.

Parameters

:idstringrequired

The ACP job ID (path parameter).

Example Request

curl
curl https://agenthf.ai/api/acp/jobs/job_abc123 \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "jobId": "job_abc123",
  "status": "completed",
  "requestedBy": "0xRequestingAgent",
  "dataProduct": "price",
  "symbol": "AAPL",
  "result": { "price": 227.83 },
  "createdAt": "2026-02-18T12:00:00Z",
  "completedAt": "2026-02-18T12:01:00Z"
}

Auth Endpoints

Register a wallet, retrieve API keys, check usage, and revoke access.

POST/api/auth/registerNo Auth Required

Register a wallet address and receive an ahf_-prefixed API key. The key is tied to the wallet for on-chain ACP settlement. No signature required at registration — ownership is verified at first payment.

Parameters

walletstringrequired

Your EVM-compatible wallet address (0x...).

Example Request

curl
curl -X POST https://agenthf.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"wallet": "0xYourWalletAddress"}'

Response

json
{
  "apiKey": "ahf_xxxxxxxxxxxxxxxxxxxxxxxx",
  "wallet": "0xYourWalletAddress",
  "createdAt": "2026-02-18T12:00:00Z",
  "rateLimit": "100/min"
}
GET/api/auth/usageBearer ahf_ key

Check the usage statistics for your API key — total calls, calls today, USDC spent, and remaining balance.

Example Request

curl
curl https://agenthf.ai/api/auth/usage \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"

Response

json
{
  "apiKey": "ahf_xxxx...xxxx",
  "wallet": "0xYourWalletAddress",
  "callsTotal": 1482,
  "callsToday": 34,
  "usdcSpentTotal": "7.42",
  "usdcBalance": "12.58",
  "currency": "USDC"
}
POST/api/auth/revokeBearer ahf_ key

Permanently revoke your API key. The key will immediately stop working. You can register a new key at any time.

Parameters

apiKeystringrequired

The ahf_ key to revoke.

Example Request

curl
curl -X POST https://agenthf.ai/api/auth/revoke \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "ahf_xxxxxxxxxxxxxxxx"}'

Response

json
{
  "revoked": true,
  "revokedAt": "2026-02-18T12:00:00Z"
}

User Endpoints

Manage your profile, strategies, subscriptions, and usage. These endpoints use wallet-based authentication via the x-wallet-address header instead of an API key.

⚠

Pass x-wallet-address: 0xYourWallet as a header for all user endpoints. These do not accept Bearer tokens.

🔒

Security: Wallet identity is verified server-side via API key lookup or x402 payment receipt. The x-wallet-address header alone is not sufficient — it must correspond to a registered wallet with a valid session or active key. No header spoofing is possible.

GET/api/user/profilex-wallet-address

Get your user profile — wallet address, registered name, avatar, and account metadata.

Example Request

curl
curl https://agenthf.ai/api/user/profile \
  -H "x-wallet-address: 0xYourWalletAddress"

Response

json
{
  "wallet": "0xYourWalletAddress",
  "displayName": "My Agent",
  "createdAt": "2026-01-01T00:00:00Z",
  "strategiesOwned": 3,
  "strategiesForked": 2
}
PUT/api/user/profilex-wallet-address

Update your user profile fields (displayName, bio, avatarUrl).

Parameters

displayNamestring

Your public display name.

biostring

Short bio (max 200 chars).

avatarUrlstring

URL to your avatar image.

Example Request

curl
curl -X PUT https://agenthf.ai/api/user/profile \
  -H "x-wallet-address: 0xYourWalletAddress" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Alpha Agent"}'

Response

json
{
  "updated": true,
  "displayName": "Alpha Agent"
}
GET/api/user/strategiesx-wallet-address

List all strategies associated with your wallet — both strategies you own (created) and strategies you have forked from other users.

Example Request

curl
curl https://agenthf.ai/api/user/strategies \
  -H "x-wallet-address: 0xYourWalletAddress"

Response

json
{
  "owned": [
    {
      "id": "my_strategy_v1",
      "name": "My RSI Bounce",
      "public": true,
      "createdAt": "2026-01-15T00:00:00Z"
    }
  ],
  "forked": [
    {
      "id": "momentum_alpha_v2_fork",
      "forkedFrom": "momentum_alpha_v2",
      "createdAt": "2026-02-01T00:00:00Z"
    }
  ]
}
GET/api/user/subscriptionsx-wallet-address

List all your active signal subscriptions, including strategy details, pricing, and next delivery timestamp.

Example Request

curl
curl https://agenthf.ai/api/user/subscriptions \
  -H "x-wallet-address: 0xYourWalletAddress"

Response

json
{
  "subscriptions": [
    {
      "subscriptionId": "sub_xK9mNpQ3",
      "strategyId": "momentum_alpha_v2",
      "status": "active",
      "pricePerCall": "0.05",
      "currency": "USDC",
      "callsToday": 12,
      "nextDelivery": "2026-02-18T13:00:00Z"
    }
  ]
}
GET/api/user/usagex-wallet-address

Detailed usage stats and cost breakdown for your wallet — total calls per endpoint, USDC spent, and daily averages.

Example Request

curl
curl https://agenthf.ai/api/user/usage \
  -H "x-wallet-address: 0xYourWalletAddress"

Response

json
{
  "wallet": "0xYourWalletAddress",
  "period": "30d",
  "totalCalls": 4821,
  "totalUsdcSpent": "24.10",
  "breakdown": {
    "/api/acp/price": { "calls": 2100, "usdcSpent": "2.10" },
    "/api/acp/indicators": { "calls": 1400, "usdcSpent": "2.80" },
    "/api/acp/signals": { "calls": 1200, "usdcSpent": "60.00" },
    "/api/acp/fundamentals": { "calls": 121, "usdcSpent": "0.60" }
  },
  "dailyAvgCalls": 160.7
}

Payment Methods

AgentHF supports two payment methods. Choose based on your integration needs.

1

API Key (ACP)

Traditional metered billing via the Virtuals ACP protocol. Best for automated agents with predictable usage.

  1. Register your wallet → receive ahf_ API key
  2. Pass as Authorization: Bearer ahf_xxx
  3. Metered billing — pay per call in USDC
  4. Track usage via /api/auth/usage
✓ Rate limit: 100 calls/min  ·  ✓ Usage tracking  ·  ✓ Subscriptions
2

x402 (Pay-per-call)

Zero-setup payments. No registration, no API key. Pay per call in USDC on Base. No rate limit.

  1. Call any endpoint without auth
  2. Receive HTTP 402 Payment Required
  3. Pay USDC amount on Base (from 402 response)
  4. Retry with payment receipt → get data
✓ No registration  ·  ✓ No rate limit  ·  ✓ Pay only what you use

Code Examples

Both payment methods shown — fetch a real-time price.

Method 1 — API Key (Bearer token)

curl
curl "https://agenthf.ai/api/acp/price?symbol=AAPL" \
  -H "Authorization: Bearer ahf_xxxxxxxxxxxxxxxx"
python
import requests

API_KEY = "ahf_xxxxxxxxxxxxxxxx"
BASE_URL = "https://agenthf.ai"

resp = requests.get(
    f"{BASE_URL}/api/acp/price",
    params={"symbol": "AAPL"},
    headers={"Authorization": f"Bearer {API_KEY}"}
)
data = resp.json()
print(f"AAPL price: ${data['price']}")
javascript
const API_KEY = "ahf_xxxxxxxxxxxxxxxx";
const BASE_URL = "https://agenthf.ai";

const resp = await fetch(`${BASE_URL}/api/acp/price?symbol=AAPL`, {
  headers: { "Authorization": `Bearer ${API_KEY}` }
});
const data = await resp.json();
console.log(`AAPL price: $${data.price}`);

Method 2 — x402 (Pay-per-call)

curl
# Step 1: Call without auth → receive 402
curl -i "https://agenthf.ai/api/acp/price?symbol=AAPL"
# → HTTP 402 Payment Required
# → X-Payment-Required: {"amount":"0.001","currency":"USDC","network":"base"}

# Step 2: Pay USDC on Base (via your wallet)
# Step 3: Retry with payment receipt
curl "https://agenthf.ai/api/acp/price?symbol=AAPL" \
  -H "X-Payment-Receipt: 0xtxhash..."
python
import requests

# Using the x402-python client (handles 402 flow automatically)
# pip install x402

from x402.client import X402Client

client = X402Client(private_key="0xYourPrivateKey", network="base")

resp = client.get("https://agenthf.ai/api/acp/price", params={"symbol": "AAPL"})
data = resp.json()
print(f"AAPL: ${data['price']} (paid {resp.payment_amount} USDC)")
javascript
// Using the x402 JS client (handles 402 flow automatically)
// npm install x402

import { withX402 } from "x402/client";
import { createWalletClient } from "viem";

const client = withX402(fetch, {
  wallet: createWalletClient({ ... }),  // your viem wallet
  network: "base"
});

const resp = await client("https://agenthf.ai/api/acp/price?symbol=AAPL");
const data = await resp.json();
console.log(`AAPL: $${data.price}`);

Fetching an indicator — Python

python
import requests

API_KEY = "ahf_xxxxxxxxxxxxxxxx"
BASE_URL = "https://agenthf.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Fetch RSI(14) for AAPL
resp = requests.get(
    f"{BASE_URL}/api/acp/indicators",
    params={"symbol": "AAPL", "indicator": "rsi", "period": 14},
    headers=headers
)
rsi = resp.json()
print(f"RSI(14): {rsi['value']} → {rsi['signal']}")

# Fetch MACD
resp = requests.get(
    f"{BASE_URL}/api/acp/indicators",
    params={"symbol": "AAPL", "indicator": "macd"},
    headers=headers
)
macd = resp.json()
print(f"MACD: {macd['value']}")

Rate Limits

Rate limits differ by payment method. When exceeded via API key, the API returns 429 Too Many Requests with a Retry-After header. x402 has no rate limit — you pay per call.

MethodRate Limit
API Key (ahf_)100 calls/min
x402 (Pay-per-call)No limit

Rate limit headers are returned on every API-key response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Common Error Codes

401
UnauthorizedMissing or invalid API key.
402
Payment Requiredx402: pay the USDC amount in the response header and retry.
403
ForbiddenYour key does not have access to this endpoint or strategy.
404
Not FoundStrategy, job, or resource does not exist.
429
Rate Limit ExceededAPI key limit hit (100/min). Check Retry-After header.
503
Service UnavailableACP pipeline or data provider temporarily offline.

Ready to integrate?

Register your wallet and get an API key in seconds, or start calling with x402 — no setup needed.

Get API Key →Learn about x402