Skip to main content

​
Base URLs

EnvironmentBase URL
Mainnethttps://api.acn.exchange
Testnethttps://api.acn-testnet.exchange
Devnethttps://api.acn-dev.net
All API paths are prefixed with /v1/. For example: 
https://api.acn.exchange/v1/discover

​
Authentication

ACN uses a wallet-first, auth-optional model. Most endpoints work without any authentication — payment is the authentication.

​
Identity Tiers

TierHow to AccessFeatures
AnonymousNo headersDiscover, execute, pay
Wallet-IdentifiedX-Acn-Wallet: 0xAddressAbove + reputation accrual, better rate limits
AuthenticatedAPI key or wallet signatureAll above + balance, history, spend limits

​
API Key

# Via dedicated header
curl https://api.acn.exchange/v1/discover \
  -H "x-acn-api-key: acn_sk_your_api_key"

# Via Authorization header
curl https://api.acn.exchange/v1/discover \
  -H "Authorization: Bearer acn_sk_your_api_key"

​
Wallet Header (No Signature Required)

curl https://api.acn.exchange/v1/discover \
  -H "X-Acn-Wallet: 0xYourWalletAddress"
Provides wallet-based rate limits and reputation tracking without any cryptographic verification.

​
Wallet Signature

curl https://api.acn.exchange/v1/discover \
  -H "X-Acn-Wallet: 0xYourAddress" \
  -H "X-Acn-Signature: 0xSignedMessage..." \
  -H "X-Acn-Nonce: nonce_from_challenge"
See Authentication for details on each method.

​
Request Format

  • All request bodies use JSON (Content-Type: application/json)
  • All responses return JSON
  • Timestamps are ISO 8601 format
  • Currency amounts are strings (to avoid floating point issues) in USDC

​
Response Format

​
Successful Responses

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Execution Responses

Execution endpoints return an acn metadata object alongside the provider’s response: 
{
  "acn": {
    "call_id": "call_abc123",
    "provider_id": "resend",
    "endpoint": "send-email",
    "charged_usdc": "0.002",
    "remaining_balance_usdc": "10.498",
    "latency_ms": 230
  },
  "data": { ... }
}

​
Error Handling

Errors follow a consistent format: 
{
  "error": {
    "code": "ACN-PAY-001",
    "message": "Insufficient balance",
    "details": {
      "required_usdc": "0.002",
      "available_usdc": "0.001"
    }
  }
}

​
Error Code Prefixes

PrefixDomain
ACN-DSC-*Discovery errors
ACN-EXE-*Execution errors
ACN-PAY-*Payment errors
ACN-AUTH-*Authentication errors
ACN-MCP-*MCP tool errors
ACN-VAL-*Validation errors
ACN-RATE-*Rate limiting errors

​
HTTP Status Codes

CodeMeaning
200Success
400Bad request — invalid parameters or request body
401Unauthorized — missing or invalid authentication
402Payment required — insufficient balance
404Not found — provider or endpoint doesn’t exist
429Rate limited — too many requests
500Internal server error
502Provider error — upstream provider returned an error
504Provider timeout — upstream provider didn’t respond in time

​
Rate Limits

Rate limits vary by identity tier and trust level:
TierRate LimitScope
Anonymous20 req/minPer IP address
Wallet-Identified (new)30 req/minPer wallet
Wallet-Identified (established)100 req/minPer wallet
Wallet-Identified (trusted)500 req/minPer wallet
Authenticated100 req/minPer developer account
Rate limit headers are included in every response: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709913600
When rate limited, the API returns 429 with a Retry-After header. See Rate Limits for complete details.

​
Pagination

List endpoints support cursor-based pagination: 
GET /v1/endpoint?limit=20&cursor=abc123

{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "def456"
  }
}

​
Idempotency

Execution calls return a unique call_id. If you need to retry a call, you can use the Idempotency-Key header to prevent duplicate charges: 
curl -X POST https://api.acn.exchange/v1/execute/resend/send-email \
  -H "Authorization: Bearer acn_sk_your_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

​
OpenAPI Specification

A machine-readable OpenAPI specification is available for the ACN API. Use it to auto-generate client libraries or import into tools like Postman:
  • Devnet: https://api.acn-dev.net/docs-json
  • Testnet: https://api.acn-testnet.exchange/docs-json
The OpenAPI spec is available on devnet and testnet environments. For mainnet, refer to this documentation.