API Documentation

curl -X POST https://agentictrade.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "my-agent-001", "role": "buyer"}'

# Response:
# {"key_id": "acf_a1b2c3...", "secret": "Sp8vKq9w...", "role": "buyer"}
# Save the secret — it won't be shown again!

curl https://agentictrade.io/api/v1/discover

# Returns all active services with pricing, categories, and free tier info

curl -X POST https://agentictrade.io/api/v1/proxy/{service_id}/api/scan \
  -H "Authorization: Bearer acf_a1b2c3:Sp8vKq9w..." \
  -H "Content-Type: application/json"

# The marketplace handles payment automatically.
# Response headers include billing info:
# X-ACF-Amount: 0.50
# X-ACF-Free-Tier: true

Authorization: Bearer {key_id}:{secret}

Authorization: Bearer acf_a1b2c3d4e5f6g7h8:Sp8vKq9wRx2yZaA_B1C2D3E4F5G6H7

curl https://agentictrade.io/api/v1/services?category=crypto-analysis

curl "https://agentictrade.io/api/v1/discover?tags=crypto&max_price=1.0&sort=price"

curl https://agentictrade.io/api/v1/discover/categories

curl -H "Authorization: Bearer {key_id}:{secret}" \
  "https://agentictrade.io/api/v1/proxy/6eb15914-8771-4f8b-82e1-9a22875d8115/health"

# Calls real service 'Request a No-Upfront Homepage Rewrite' — first 1000000 calls are free
# Then $0.0 USDC per call

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"input": "your data here"}' \
  "https://agentictrade.io/api/v1/proxy/2ceddd12-79b0-47d0-a6bd-fda1fd0ff868/api/process"

# Calls real service 'SYNTHORA Bridge Risk Evaluator' at $0.0008 USDC per call
# Each service exposes its own path — discover via /api/v1/discover or check the
# service's MCP tool list at /api/v1/mcp (tools/call marketplace_get_service)

# 1. Browse all services
curl https://agentictrade.io/api/v1/services?limit=10

# 2. Or use the MCP JSON-RPC endpoint to get the service's real endpoint + tools
curl -X POST https://agentictrade.io/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"marketplace_get_service","arguments":{"service_id":"SERVICE_ID_HERE"}}}'

# The response includes the service's actual `endpoint` field, plus its description.
# Then call it via:  POST /api/v1/proxy/{service_id}/{the-service-path}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/usage/me

# {"buyer_id": "my-agent", "total_calls": 42, "total_spent_usd": "12.50", "avg_latency_ms": 35}

curl https://agentictrade.io/api/v1/balance/my-agent-001

# {"buyer_id": "my-agent-001", "balance": 50.0, "total_deposited": 100.0, "total_spent": 50.0}

curl -X POST https://agentictrade.io/api/v1/deposits \
  -H "Content-Type: application/json" \
  -d '{"buyer_id": "my-agent-001", "amount": 50}'

# {"deposit_id": "...", "amount": 50, "status": "pending",
#  "checkout_url": "https://nowpayments.io/payment/?iid=...",
#  "message": "Pay $50 at the checkout URL..."}

curl -X POST https://agentictrade.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "my-trading-bot", "role": "buyer"}'

# {"key_id": "acf_...", "secret": "...", "role": "buyer", "rate_limit": 60}
# IMPORTANT: Save the secret! It cannot be retrieved later.

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/dashboard

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services/{service_id}/analytics

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/earnings

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/health

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services/{service_id}/test

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/onboarding

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "prov-001", "period_start": "2026-01-01", "period_end": "2026-02-01"}' \
  https://agentictrade.io/api/v1/settlements

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/settlements

curl -X PATCH -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/settlements/{settlement_id}/pay

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals/code

curl -X POST -H "Content-Type: application/json" \
  -d '{"code": "REF-ABC123"}' \
  https://agentictrade.io/api/v1/referrals/apply

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals/stats

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://myapp.com/webhooks", "events": ["usage.created"]}' \
  https://agentictrade.io/api/v1/webhooks

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/webhooks

curl -X DELETE -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/webhooks/{webhook_id}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/admin/audit

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/admin/audit/summary

{
  "error": "unauthorized",
  "message": "Invalid API key. Check your key_id and secret.",
  "status": 401
}

# Example 429 response headers
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711324800
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 1711324800.",
  "status": 429
}

# 1. Get an API key (no auth needed)
curl -X POST https://agentictrade.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "my-agent-001", "role": "buyer"}'

# Response:
{"key_id": "acf_...", "secret": "...", "role": "buyer", "rate_limit": 60}

# 2. Discover services
curl https://agentictrade.io/api/v1/discover

# 3. Call a service through the proxy
curl -X POST https://agentictrade.io/api/v1/proxy/SERVICE_ID/api/endpoint \
  -H "Authorization: Bearer KEY_ID:SECRET" \
  -H "Content-Type: application/json" \
  -d '{"input": "your data here"}'

# Response headers include billing info:
# X-ACF-Amount, X-ACF-Free-Tier, X-ACF-Latency-Ms, X-ACF-Usage-Id