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

Most endpoints require authentication via API key: 
Authorization: Bearer acn_sk_your_api_key
Or wallet signature: 
Authorization: Wallet <address>:<signature>:<timestamp>:<nonce>
Exception: The discovery endpoint (POST /v1/discover) is public and does not require authentication. See Authentication for details on both methods.

​
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-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 limit headers are included in every response: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709913600
AuthenticationLimit
Unauthenticated20 requests/minute
Authenticated100 requests/minute
When rate limited, the API returns 429 with a Retry-After header.

​
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.