Skip to main content
This guide walks you through discovering and executing a service using ACN’s REST API directly.

​
Prerequisites

  • An ACN account (sign up)
  • An API key (created from the dashboard)
  • USDC on Base (for executing paid calls)

​
Step 1: Discover Services

Discovery is free and unauthenticated. Describe what you need in natural language: 
curl -X POST https://api.acn.exchange/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "query": "get the current price of Bitcoin"
  }'
Response: 
{
  "results": [
    {
      "provider_id": "coingecko",
      "provider_name": "CoinGecko",
      "endpoint_slug": "get-price",
      "description": "Get current cryptocurrency prices in any fiat or crypto denomination",
      "pricing": {
        "model": "per_call",
        "price_per_call_usdc": "0.001"
      },
      "quality": {
        "uptime_pct": 99.8,
        "avg_latency_ms": 120,
        "total_calls": 50420
      },
      "relevance_score": 0.97
    }
  ]
}
You can also use structured filters alongside natural language: 
curl -X POST https://api.acn.exchange/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cryptocurrency prices",
    "filters": {
      "category": "data_intelligence",
      "max_price_per_call": 0.01
    }
  }'

​
Step 2: Check Your Balance

Before executing a paid call, verify you have sufficient funds: 
curl https://api.acn.exchange/v1/wallet/balance \
  -H "Authorization: Bearer acn_sk_your_api_key"

{
  "balance_usdc": "10.50",
  "total_deposited_usdc": "25.00",
  "total_spent_usdc": "14.50"
}
Need to deposit funds? See the Deposit Funds guide.

​
Step 3: Execute a Call

Call the service you discovered. ACN handles authentication with the provider, payment, and response wrapping: 
curl -X POST https://api.acn.exchange/v1/execute/coingecko/get-price \
  -H "Authorization: Bearer acn_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": "bitcoin",
    "vs_currencies": "usd"
  }'
Response: 
{
  "acn": {
    "call_id": "call_abc123",
    "provider_id": "coingecko",
    "endpoint": "get-price",
    "charged_usdc": "0.001",
    "remaining_balance_usdc": "10.499",
    "latency_ms": 145
  },
  "data": {
    "bitcoin": {
      "usd": 67542.00
    }
  }
}
The acn field contains metadata about the call. The data field contains the provider’s actual response.

​
Step 4: Review Your Usage

Check your call history: 
curl https://api.acn.exchange/v1/wallet/history \
  -H "Authorization: Bearer acn_sk_your_api_key"

​
What’s Next?

Build an Agent

Let an AI agent use ACN autonomously

API Reference

Full API documentation

Discovery Deep Dive

Understand how discovery ranking works

Manage API Keys

Create and rotate your API keys