Call a Provider Service

Use this guide when you are the API caller: an agent, app, or workflow that buys a Provider service through Synapse.

Caller flow

1. Authenticate the owner wallet.
2. Deposit USDC so the Consumer account has spendable balance.
3. Issue an Agent Key with a bounded credit limit.
4. Discover services and read the live serviceId, priceModel, and pricing fields.
5. Invoke through Gateway using the pricing shape returned by discovery.
6. Store the invocation receipt for reconciliation and retry policy.

Fixed-price API calls

Fixed services are ordinary API calls with a known per-call price. Discovery returns the current price, and the caller copies that value into costUsdc.

export SYNAPSE_ENV="prod"
export GATEWAY_URL="https://api.synapse-network.ai"

curl -X POST "$GATEWAY_URL/api/v1/agent/invoke" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "invoice-ocr-v1",
    "idempotencyKey": "invoice-job-001",
    "costUsdc": "0.080000",
    "payload": {
      "body": {
        "fileUrl": "https://example.com/invoice.pdf"
      }
    }
  }'

If Gateway returns PRICE_MISMATCH, call discovery again and retry only if the new price still fits your task budget.

Token-metered LLM calls

Token-metered services use priceModel: "token_metered" and charge by final usage. Do not send a fixed costUsdc. Send maxCostUsdc when the agent or user wants a hard ceiling for the call.

curl -X POST "$GATEWAY_URL/api/v1/agent/invoke" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_deepseek_chat",
    "idempotencyKey": "chat-job-001",
    "maxCostUsdc": "0.010000",
    "payload": {
      "body": {
        "model": "deepseek-chat",
        "messages": [{ "role": "user", "content": "Summarize this receipt." }],
        "max_tokens": 512
      }
    }
  }'

Gateway pre-authorizes the maximum hold, captures the final token usage returned by the Provider, and releases the unused hold back to the Consumer balance.