API Reference

Complete reference for the AgnicPay API.

Base URL

https://api.agnic.ai

Authentication

AgnicPay supports two authentication methods:

API Token

curl https://api.agnic.ai/api/balance \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"

OAuth2 Bearer Token

curl https://api.agnic.ai/api/balance \
  -H "Authorization: Bearer agnic_at_YOUR_OAUTH_TOKEN"

Endpoints Overview

X402 Payments

Method	Endpoint	Description
POST	`/api/x402/fetch`	Transparent X402 payment proxy (recommended)
POST	`/api/sign-payment`	Sign X402 payment proof

Token Trading

Method	Endpoint	Description
POST	`/api/trade`	Execute token swap on Base
GET	`/api/trade/quote`	Get trade quote (dry run)
GET	`/api/trade/tokens`	List supported tokens

Balance & Transactions

Method	Endpoint	Description
GET	`/api/balance`	Get wallet USDC balance
GET	`/api/transactions`	Get transaction history

Token Management

Method	Endpoint	Description
GET	`/api/tokens`	List API tokens
POST	`/api/generate-n8n-token`	Create new API token
POST	`/api/revoke-token`	Revoke API token

OAuth

Method	Endpoint	Description
GET	`/oauth/authorize`	Start OAuth flow
POST	`/oauth/token`	Exchange code for tokens
POST	`/oauth/complete-authorization`	Complete authorization

AI Gateway

Method	Endpoint	Description
POST	`/v1/chat/completions`	OpenAI-compatible chat
GET	`/v1/models`	List available models

X402 Fetch (Recommended)

POST /api/x402/fetch?url={target_url}

Transparent proxy that automatically handles 402 responses.

Query Parameters

Parameter	Type	Required	Description
`url`	string	Yes	Target URL to fetch
`method`	string	No	HTTP method (default: GET)
`maxValue`	integer	No	Max payment in atomic units
`timeout`	integer	No	Timeout in ms (default: 30000)

Request Body

Forward any JSON body to the target URL.

Response Headers

Header	Description
`X-Agnic-Paid`	"true" or "false"
`X-Agnic-Amount`	Amount paid in USD
`X-Agnic-Network`	Network used
`X-Agnic-Scheme`	"exact" or "upto"

Example

curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/data" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello"}'

Sign Payment

POST /api/sign-payment

Sign an X402 payment proof manually.

Request Body

{
  "paymentRequirements": {
    "accepts": [{
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "250000",
      "maxTimeoutSeconds": 300,
      "resource": "https://api.example.com/endpoint",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "extra": { "name": "USD Coin", "version": "2" }
    }]
  },
  "requestData": {
    "url": "https://api.example.com/endpoint",
    "method": "POST"
  }
}

Response

{
  "success": true,
  "paymentHeader": "eyJ2ZXJzaW9uIjox...",
  "amountPaid": 0.25,
  "network": "base-sepolia",
  "scheme": "exact"
}

Get Balance

GET /api/balance

Query Parameters

Parameter	Type	Description
`network`	string	Network (default: base-sepolia)

Response

{
  "usdcBalance": "50.000000",
  "address": "0x1234...",
  "hasWallet": true,
  "network": "base-sepolia"
}

Get Transactions

GET /api/transactions

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`status`	string	Filter by status
`search`	string	Search by endpoint

Response

{
  "transactions": [
    {
      "id": "tx_123",
      "amount_usd": 0.25,
      "network": "base-sepolia",
      "endpoint": "https://api.example.com",
      "timestamp": "2025-01-09T12:00:00Z",
      "status": "success"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 100
  },
  "stats": {
    "totalSpent": 25.50,
    "successRate": 95.0
  }
}

Chat Completions (AI Gateway)

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint.

Request Body

{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": false
}

Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "model": "openai/gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Error Responses

All endpoints return errors in this format:

{
  "error": "error_code",
  "error_description": "Human-readable description"
}

Common Error Codes

Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing token
`spending_limit_exceeded`	402	Limit exceeded
`insufficient_balance`	402	Not enough USDC
`invalid_request`	400	Bad request parameters
`server_error`	500	Internal error

Rate Limits

Endpoint	Rate Limit
All endpoints	1000 req/min
AI Gateway	100 req/min

Exceeding limits returns 429 Too Many Requests.

OpenAPI Specification

Download the full OpenAPI spec:

https://api.agnic.ai/.well-known/openapi.yaml

API Reference

On this page