{% extends "public/base.html" %} {% block title %}{{ t('docs.page_title') if t else 'API Documentation — AgenticTrade' }}{% endblock %} {% block meta_description %}{{ t('docs.meta_desc') if t else 'AgenticTrade API documentation. Build AI agents that discover and consume API services autonomously with USDC payments. Quick start, SDK, and full endpoint reference.' }}{% endblock %} {% block og_title %}{{ t('docs.page_title') if t else 'API Documentation — AgenticTrade' }}{% endblock %} {% block og_description %}{{ t('docs.subtitle') if t else 'Build AI agents that discover and consume services autonomously. Full API reference with code examples.' }}{% endblock %} {% block tw_title %}{{ t('docs.page_title') if t else 'API Documentation — AgenticTrade' }}{% endblock %} {% block tw_description %}{{ t('docs.subtitle') if t else 'Build AI agents that discover and consume services autonomously. Full API reference with code examples.' }}{% endblock %} {% block json_ld %} {% endblock %} {% block extra_css %} {% endblock %} {% block content %}

{{ t('docs.title') if t else 'API Documentation' }}

{{ t('docs.subtitle') if t else 'Build AI agents that discover and consume services autonomously.' }}

Base URL: https://agentictrade.io/api/v1

{{ t('docs.quick_start') if t else 'Quick Start' }}

{{ t('docs.quickstart_desc') if t else 'Get your agent calling services in 3 steps:' }}

{{ t('docs.step1_title') if t else 'Create an API Key' }}

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!

{{ t('docs.step2_title') if t else 'Browse Available Services' }}

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

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

{{ t('docs.step3_title') if t else 'Call a Service' }}

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

{{ t('docs.authentication') if t else 'Authentication' }}

{{ t('docs.auth_desc') if t else 'All authenticated endpoints use Bearer token authentication:' }}

Authorization: Bearer {key_id}:{secret}

{{ t('docs.auth_example') if t else 'Example:' }}

Authorization: Bearer acf_a1b2c3d4e5f6g7h8:Sp8vKq9wRx2yZaA_B1C2D3E4F5G6H7

{{ t('docs.roles') if t else 'Roles' }}

{{ t('docs.role_header') if t else 'Role' }}{{ t('docs.role_can_do') if t else 'Can Do' }}
buyer{{ t('docs.role_buyer_desc') if t else 'Call services via proxy, check balance, view usage' }}
provider{{ t('docs.role_provider_desc') if t else 'Register and manage services, view earnings' }}
admin{{ t('docs.role_admin_desc') if t else 'Full platform access' }}

{{ t('docs.rate_limits') if t else 'Rate Limits' }}

{{ t('docs.tier') if t else 'Tier' }}{{ t('docs.limit') if t else 'Limit' }}
{{ t('docs.tier_default') if t else 'Default' }}{{ t('docs.requests_per_min_60') if t else '60 requests / minute' }}
{{ t('docs.tier_maximum') if t else 'Maximum' }}{{ t('docs.requests_per_min_300') if t else '300 requests / minute' }}

{{ t('docs.available_services') if t else 'Available Services' }}

{% for svc in services %}

{{ svc.name }}

{{ svc.description[:120] }}{% if svc.description|length > 120 %}...{% endif %}

{% if svc.price_per_call == 0 or svc.price_per_call == '0' or svc.price_per_call == '0.0' %} {{ t('docs.pricing_free') if t else 'FREE' }} {% else %} ${{ svc.price_per_call }} {{ t('docs.per_call') if t else '/ call' }} {% endif %} {% if svc.free_tier_calls and svc.free_tier_calls > 0 %} {{ svc.free_tier_calls }} {{ t('docs.free_badge') if t else 'free' }} {% endif %}
ID: {{ svc.id }}
{% endfor %}

{{ t('docs.service_discovery') if t else 'Service Discovery' }}

GET /api/v1/services {{ t('docs.endpoint_list_services') if t else 'List all services' }}

{{ t('docs.endpoint_list_services_desc') if t else 'Returns all registered services with pricing info. No authentication required.' }}

{{ t('docs.query_params') if t else 'Query Parameters' }}

{{ t('docs.param') if t else 'Param' }}{{ t('docs.type') if t else 'Type' }}{{ t('docs.description') if t else 'Description' }}
categorystring{{ t('docs.param_category_desc') if t else 'Filter by category' }}
querystring{{ t('docs.param_query_desc') if t else 'Search by name/description' }}
limitint{{ t('docs.param_limit_desc') if t else 'Max results (default: 50)' }}
offsetint{{ t('docs.param_offset_desc') if t else 'Pagination offset' }}
 
curl https://agentictrade.io/api/v1/services?category=crypto-analysis
GET /api/v1/discover {{ t('docs.endpoint_advanced_discovery') if t else 'Advanced service discovery' }}

{{ t('docs.endpoint_advanced_discovery_desc') if t else 'Enhanced discovery with filtering, sorting, and tag matching.' }}

{{ t('docs.query_params') if t else 'Query Parameters' }}

{{ t('docs.param') if t else 'Param' }}{{ t('docs.type') if t else 'Type' }}{{ t('docs.description') if t else 'Description' }}
tagsstring{{ t('docs.param_tags_desc') if t else 'Comma-separated tag filter' }}
min_pricefloat{{ t('docs.param_min_price_desc') if t else 'Minimum price per call' }}
max_pricefloat{{ t('docs.param_max_price_desc') if t else 'Maximum price per call' }}
sortstring{{ t('docs.param_sort_desc') if t else 'Sort by: price, name, created' }}
 
curl "https://agentictrade.io/api/v1/discover?tags=crypto&max_price=1.0&sort=price"
GET /api/v1/discover/categories {{ t('docs.endpoint_list_categories') if t else 'List categories' }}

{{ t('docs.endpoint_list_categories_desc') if t else 'Returns available service categories with service counts.' }}

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

{{ t('docs.proxy_title') if t else 'Proxy — Call Services' }}

{{ t('docs.proxy_info') if t else 'This is the core endpoint. Your agent sends requests here; the marketplace handles routing, payment, and usage tracking.' }}
POST /api/v1/proxy/{service_id}/{path} {{ t('docs.endpoint_call_service') if t else 'Call a service' }}

{{ t('docs.proxy_desc') if t else 'Proxies your request to the service provider. Supports GET, POST, PUT, PATCH, DELETE.' }}

{{ t('docs.path_params') if t else 'Path Parameters' }}

{{ t('docs.param') if t else 'Param' }}{{ t('docs.description') if t else 'Description' }}
service_id{{ t('docs.param_service_id_desc') if t else 'UUID of the target service' }}
path{{ t('docs.param_path_desc') if t else 'The API path on the provider' }} (e.g., api/scan)

{{ t('docs.response_headers') if t else 'Response Headers' }}

{{ t('docs.header') if t else 'Header' }}{{ t('docs.description') if t else 'Description' }}
X-ACF-Usage-Id{{ t('docs.header_usage_id_desc') if t else 'Unique usage record ID' }}
X-ACF-Amount{{ t('docs.header_amount_desc') if t else 'Amount charged (USDC)' }}
X-ACF-Free-Tiertrue {{ t('docs.header_free_tier_desc') if t else 'if free tier was used' }}
X-ACF-Latency-Ms{{ t('docs.header_latency_desc') if t else 'Request latency in milliseconds' }}

{{ t('docs.example_demo') if t else 'Example: CoinSifter Demo (free)' }}

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

# Returns real-time crypto scan results

{{ t('docs.example_scanner') if t else 'Example: CoinSifter Scanner ($0.50/call)' }}

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

# Triggers a full market scan with your strategy

{{ t('docs.example_backtest') if t else 'Example: Strategy Backtest ($2.00/call)' }}

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC/USDT", "strategy": "bb_squeeze", "timeframe": "4h"}' \
  "https://agentictrade.io/api/v1/proxy/{{ backtest_service_id }}/api/backtest"

# Returns win rate, profit factor, equity curve, trade list
GET /api/v1/usage/me {{ t('docs.endpoint_usage_stats') if t else 'Your usage stats' }}

{{ t('docs.endpoint_usage_stats_desc') if t else 'Returns total calls, spend, and average latency for the authenticated buyer.' }}

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}

{{ t('docs.billing_title') if t else 'Billing & Deposits' }}

{{ t('docs.billing_desc') if t else 'Services are pre-paid. Deposit funds to your account, then call services.' }}

{{ t('docs.billing_free_note') if t else 'Most services include free tier calls. You only need to deposit when free calls run out.' }}
GET /api/v1/balance/{buyer_id} {{ t('docs.endpoint_check_balance') if t else 'Check balance' }} 
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}
POST /api/v1/deposits {{ t('docs.endpoint_add_funds') if t else 'Add funds' }}

{{ t('docs.add_funds_desc') if t else 'Creates a crypto payment invoice via NOWPayments. Supports USDT, USDC, BTC, ETH, and 100+ cryptocurrencies.' }}

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..."}

{{ t('docs.add_funds_note') if t else 'After payment confirms, your balance is automatically credited via IPN webhook.' }}

{{ t('docs.keys_title') if t else 'API Keys' }}

POST /api/v1/keys {{ t('docs.endpoint_create_key') if t else 'Create API key' }}

{{ t('docs.request_body') if t else 'Request Body' }}

{{ t('docs.field') if t else 'Field' }}{{ t('docs.type') if t else 'Type' }}{{ t('docs.required') if t else 'Required' }}{{ t('docs.description') if t else 'Description' }}
owner_idstring{{ t('docs.yes') if t else 'Yes' }}{{ t('docs.field_owner_id_desc') if t else 'Your agent/user identifier' }}
rolestring{{ t('docs.no') if t else 'No' }}{{ t('docs.field_role_desc') if t else 'buyer (default) or provider' }}
 
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.

{{ t('docs.provider_title') if t else 'Provider' }}

{{ t('docs.provider_desc') if t else 'Endpoints for service providers to manage their services, view earnings, and track health. All require provider-role authentication.' }}

GET /api/v1/provider/dashboard {{ t('docs.endpoint_provider_overview') if t else 'Provider overview' }}

{{ t('docs.endpoint_provider_overview_desc') if t else 'Returns service count, total calls, revenue, and settlement status for the authenticated provider.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/dashboard
GET /api/v1/provider/services {{ t('docs.endpoint_list_your_services') if t else 'List your services' }}

{{ t('docs.endpoint_list_your_services_desc') if t else 'Returns all services owned by the authenticated provider with usage stats.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services
GET /api/v1/provider/services/{service_id}/analytics {{ t('docs.endpoint_service_analytics') if t else 'Service analytics' }}

{{ t('docs.endpoint_service_analytics_desc') if t else 'Detailed analytics for a specific service: total calls, revenue, success rate, daily breakdown.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services/{service_id}/analytics
GET /api/v1/provider/earnings {{ t('docs.endpoint_earnings') if t else 'Earnings summary' }}

{{ t('docs.endpoint_earnings_desc') if t else 'Returns total earned, settled, pending amounts, and settlement history.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/earnings
GET /api/v1/provider/health {{ t('docs.endpoint_health_scores') if t else 'Service health scores' }}

{{ t('docs.endpoint_health_scores_desc') if t else 'Returns health scores for all your services based on latency, error rate, and uptime.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/health
POST /api/v1/provider/services/{service_id}/test {{ t('docs.endpoint_test_service') if t else 'Test service endpoint' }}

{{ t('docs.endpoint_test_service_desc') if t else 'Tests connectivity to your service endpoint. Returns reachability, latency, and status code.' }}

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services/{service_id}/test
GET /api/v1/provider/onboarding {{ t('docs.endpoint_onboarding') if t else 'Onboarding progress' }}

{{ t('docs.endpoint_onboarding_desc') if t else 'Track your onboarding progress: API key creation, service registration, first traffic, first settlement.' }}

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

{{ t('docs.settlements_title') if t else 'Settlements' }}

{{ t('docs.settlements_desc') if t else 'Admin endpoints for managing provider payouts.' }}

POST /api/v1/settlements {{ t('docs.endpoint_create_settlement') if t else 'Create settlement' }}

{{ t('docs.endpoint_create_settlement_desc') if t else 'Creates a new settlement for a provider. Requires admin role.' }}

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
GET /api/v1/settlements {{ t('docs.endpoint_list_settlements') if t else 'List settlements' }}

{{ t('docs.endpoint_list_settlements_desc') if t else 'Lists all settlements, optionally filtered by provider or status.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/settlements
PATCH /api/v1/settlements/{settlement_id}/pay {{ t('docs.endpoint_execute_payment') if t else 'Execute settlement payment' }}

{{ t('docs.endpoint_execute_payment_desc') if t else 'Marks a settlement as paid and triggers the on-chain transfer.' }}

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

{{ t('docs.referrals_title') if t else 'Referrals' }}

{{ t('docs.referrals_desc') if t else 'Referral program endpoints for generating and tracking referral codes.' }}

POST /api/v1/referrals/code {{ t('docs.endpoint_create_referral') if t else 'Create referral code' }}

{{ t('docs.endpoint_create_referral_desc') if t else 'Generates a unique referral code for the authenticated user.' }}

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals/code
POST /api/v1/referrals/apply {{ t('docs.endpoint_apply_referral') if t else 'Apply referral code' }}

{{ t('docs.endpoint_apply_referral_desc') if t else 'Apply a referral code during registration to link accounts.' }}

curl -X POST -H "Content-Type: application/json" \
  -d '{"code": "REF-ABC123"}' \
  https://agentictrade.io/api/v1/referrals/apply
GET /api/v1/referrals {{ t('docs.endpoint_list_referrals') if t else 'List referrals' }}

{{ t('docs.endpoint_list_referrals_desc') if t else 'Lists all referrals made by the authenticated user.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals
GET /api/v1/referrals/stats {{ t('docs.endpoint_referral_stats') if t else 'Referral stats' }}

{{ t('docs.endpoint_referral_stats_desc') if t else 'Aggregated referral statistics: total referrals, conversion rate, and earnings.' }}

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

{{ t('docs.webhooks_title') if t else 'Webhooks' }}

{{ t('docs.webhooks_desc') if t else 'Subscribe to real-time event notifications.' }}

POST /api/v1/webhooks {{ t('docs.endpoint_create_webhook') if t else 'Create webhook' }}

{{ t('docs.endpoint_create_webhook_desc') if t else 'Registers a new webhook endpoint to receive event notifications.' }}

{{ t('docs.request_body') if t else 'Request Body' }}

{{ t('docs.field') if t else 'Field' }}{{ t('docs.type') if t else 'Type' }}{{ t('docs.description') if t else 'Description' }}
urlstring{{ t('docs.webhook_url_desc') if t else 'HTTPS endpoint to receive events' }}
eventsarray{{ t('docs.webhook_events_desc') if t else 'Event types to subscribe' }}: usage.created, settlement.completed, etc.
 
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
GET /api/v1/webhooks {{ t('docs.endpoint_list_webhooks') if t else 'List webhooks' }}

{{ t('docs.endpoint_list_webhooks_desc') if t else 'Lists all registered webhooks for your account.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/webhooks
DELETE /api/v1/webhooks/{webhook_id} {{ t('docs.endpoint_delete_webhook') if t else 'Delete webhook' }}

{{ t('docs.endpoint_delete_webhook_desc') if t else 'Removes a webhook subscription.' }}

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

{{ t('docs.audit_title') if t else 'Audit' }}

{{ t('docs.audit_desc') if t else 'Security audit endpoints for tracking platform activity. Requires admin role.' }}

GET /api/v1/admin/audit {{ t('docs.endpoint_audit_log') if t else 'Audit log' }}

{{ t('docs.endpoint_audit_log_desc') if t else 'Returns the security audit log with filtering options.' }}

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/admin/audit
GET /api/v1/admin/audit/summary {{ t('docs.endpoint_audit_summary') if t else 'Audit summary' }}

{{ t('docs.endpoint_audit_summary_desc') if t else 'Aggregated audit statistics: event counts by type and time period.' }}

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

{{ t('docs.sdk_title') if t else 'Python SDK' }}

{{ t('docs.sdk_desc') if t else 'Use the bundled SDK for seamless integration:' }}

from sdk.client import ACFClient

client = ACFClient(
    base_url="https://agentictrade.io",
    api_key="acf_xxx:secret_yyy",
)

# Discover services
services = client.list_services(category="crypto-analysis")

# Call a service through the proxy
result = client.proxy(
    service_id="{{ scanner_service_id }}",
    path="api/scan",
    method="POST",
)
print(result["results"])

{{ t('docs.agent_guide_title') if t else 'Agent Integration Guide' }}

{{ t('docs.agent_guide_desc') if t else 'How an autonomous agent uses AgenticTrade:' }}

{{ t('docs.agent_step1') if t else 'Agent discovers available services' }}

GET /api/v1/discover — {{ t('docs.agent_step1_desc') if t else 'finds services matching its task.' }}

{{ t('docs.agent_step2') if t else 'Agent checks its balance' }}

GET /api/v1/balance/{buyer_id} — {{ t('docs.agent_step2_desc') if t else 'ensures sufficient funds.' }}

{{ t('docs.agent_step3') if t else 'Agent calls the service' }}

POST /api/v1/proxy/{service_id}/{path} — {{ t('docs.agent_step3_desc') if t else 'marketplace handles payment.' }}

{{ t('docs.agent_step4') if t else 'Agent processes the response' }}

{{ t('docs.agent_step4_desc') if t else 'Response body from the provider + billing headers from the marketplace.' }}

{{ t('docs.pricing_title') if t else 'Pricing' }}

{% for svc in services %} {% endfor %}
{{ t('docs.pricing_service') if t else 'Service' }}{{ t('docs.pricing_price') if t else 'Price' }}{{ t('docs.pricing_free_tier') if t else 'Free Tier' }}{{ t('docs.pricing_payment') if t else 'Payment' }}
{{ svc.name }} {% if svc.price_per_call == 0 or svc.price_per_call == '0' or svc.price_per_call == '0.0' %} {{ t('docs.pricing_free') if t else 'FREE' }} {% else %} ${{ svc.price_per_call }} USDC {% endif %} {% if svc.free_tier_calls %}{{ svc.free_tier_calls }} {{ t('docs.pricing_calls') if t else 'calls' }}{% else %}{{ t('docs.pricing_always_free') if t else 'Always free' }}{% endif %} {{ t('docs.pricing_crypto') if t else 'Crypto (100+ coins)' }}
{{ t('docs.pricing_commission') if t else 'Platform commission: 0% for month 1, 5% for months 2–6, 10% after (capped). Deposits accepted via NOWPayments (USDT, USDC, BTC, ETH, and 100+ cryptocurrencies).' }}
© 2025-2026 AgenticTrade by JudyAI Lab. {{ t('docs.footer_copyright') if t else 'All rights reserved.' }}
{% endblock %} {% block extra_js %} {% endblock %}