Execute a Service Call
POST /v1/execute/:providerId/:endpointSlug
Authentication required. Use an API key or wallet signature.
Path Parameters
| Parameter | Type | Description |
|---|
providerId | string | Provider identifier (from discovery results) |
endpointSlug | string | Endpoint slug (from discovery results) |
Request Body
The request body is pass-through — it’s forwarded directly to the provider after validation against the endpoint’s schema.
Refer to the endpoint.parameters field from discovery results for the expected schema.
Example
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,ethereum",
"vs_currencies": "usd"
}'
Response
{
"acn": {
"call_id": "call_7f8a9b2c",
"provider_id": "coingecko",
"endpoint": "get-price",
"charged_usdc": "0.001",
"remaining_balance_usdc": "10.499",
"latency_ms": 145
},
"data": {
"bitcoin": { "usd": 67542.00 },
"ethereum": { "usd": 3521.80 }
}
}
Response Fields
| Field | Type | Description |
|---|
acn.call_id | string | Unique identifier for this call |
acn.provider_id | string | Provider that served the request |
acn.endpoint | string | Endpoint that was called |
acn.charged_usdc | string | Amount charged for this call |
acn.remaining_balance_usdc | string | Your remaining balance after the charge |
acn.latency_ms | number | Total round-trip time in milliseconds |
data | object | The provider’s response (varies by endpoint) |
Execution Pipeline
- Resolve — Verify the provider and endpoint exist
- Validate — Check the request body against the endpoint’s schema
- Debit — Atomically deduct the call cost from your balance
- Proxy — Forward the request to the provider
- Log — Record the call with metadata (timing, cost, status)
- Return — Wrap the provider’s response with ACN metadata
Automatic Refunds
| Provider Response | Refund? |
|---|
| 2xx (success) | No — call charged normally |
| 4xx (client error) | No — the request was malformed (caller’s responsibility) |
| 5xx (server error) | Yes — automatic refund |
| Timeout | Yes — automatic refund |
Error Codes
| Code | Description |
|---|
ACN-EXE-001 | Provider not found |
ACN-EXE-002 | Endpoint not found |
ACN-EXE-003 | Request validation failed — body doesn’t match endpoint schema |
ACN-EXE-004 | Provider error — upstream returned 5xx (refund issued) |
ACN-EXE-005 | Provider timeout (refund issued) |
ACN-PAY-001 | Insufficient balance |
ACN-AUTH-001 | Missing or invalid authentication |
Idempotency
To prevent duplicate charges on retries, use the Idempotency-Key header:
curl -X POST https://api.acn.exchange/v1/execute/resend/send-email \
-H "Authorization: Bearer acn_sk_your_key" \
-H "Idempotency-Key: my-unique-request-id" \
-H "Content-Type: application/json" \
-d '{ ... }'
