Protocol Overview

The ApiCharge protocol defines how clients interact with the service to request quotes, purchase access, and use monetized APIs. This page provides a high-level overview of the protocol flow and key components.

ApiCharge Protocol Flow

1. Request Quotes

2. Select Quote

3. Purchase Access

4. Use Service

Protocol Endpoints

ApiCharge exposes several REST API endpoints for client interaction:

Endpoint	Method	Description
`/apicharge/quote`	GET	Retrieve available quotes for all routes
`/apicharge/nanosubscription/PurchaseInstruction`	POST	Get purchase instructions for a selected quote
`/apicharge/nanosubscription/Purchase`	POST	Complete a purchase and receive an access token
`/apicharge/account`	GET	Get information about current accounts

Note: All cryptographic operations in the protocol use the Stellar blockchain's ED25519 signature scheme for secure verification.

Step 1: Requesting Quotes

The first step in the protocol is for the client to request available quotes from the ApiCharge server.

Quote Request

GET /apicharge/quote

Quote Response

{
  "quotes": [
    {
      "signingPubkey": "GATCBZKXPNCVBKY5KLXSWLNUAXMUPARGW5JBSP75XYU6P3AK4JUMNXQ5",
      "signature": "3rvQJW9BF4LLMrqxP6J9F6Vx8GVLUxdBf6Qd9eK95H2RQ3mS97nSQypGWGQatrP7LnDnbsMVYZ2Fj6DBLaQkBSUB",
      "signableEntity": {
        "routeId": "basic-api",
        "duration": 3600,
        "microUnitPrice": 100000,
        "validUntilUnixTimeStamp": 1683456789,
        "rateLimiters": [
          {
            "$type": "CallCount",
            "Count": 100
          }
        ]
      }
    },
    {
      "signingPubkey": "GATCBZKXPNCVBKY5KLXSWLNUAXMUPARGW5JBSP75XYU6P3AK4JUMNXQ5",
      "signature": "2wQsSr8pTjb5DtBHFmRZg3yCMkMnzipGFQS39RzGZ9drWTaAuWxQWbAMgnKg5ZN9NCpv2LiT8ULfL7p6k8GhjCxE",
      "signableEntity": {
        "routeId": "premium-api",
        "duration": 86400,
        "microUnitPrice": 1000000,
        "validUntilUnixTimeStamp": 1683456789,
        "rateLimiters": [
          {
            "$type": "CallCount",
            "Count": 1000
          },
          {
            "$type": "DataLimitDownload",
            "Bytes": 104857600
          }
        ]
      }
    }
  ]
}

Each quote includes:

The route ID it applies to
Duration of access in seconds
Price in micro units (e.g., 1 XLM = 10,000,000 micro units)
Rate limiter configurations
A digital signature from the server
Expiration timestamp for the quote itself

For detailed information about the quote request and response format, see the Purchase Flow page.

Step 2: Selecting a Quote

After receiving the quotes, the client selects one based on their needs and prepares for purchase. The selection process happens client-side, with no server interaction required.

Selection criteria might include:

Required route access
Duration needs
Budget constraints
Quality of service requirements

Step 3: Purchasing Access

The purchase process involves two steps: requesting purchase instructions and completing the purchase.

3.1 Request Purchase Instructions

POST /apicharge/nanosubscription/PurchaseInstruction
Content-Type: application/json

{
  "clientPublicKey": "GBXDGHXCQVZUDDD4NNGBOGCXYQFKNBPIMJWW7GMUCQ2OJCPO7B3GIXWA",
  "routeQuote": {
    "signingPubkey": "GATCBZKXPNCVBKY5KLXSWLNUAXMUPARGW5JBSP75XYU6P3AK4JUMNXQ5",
    "signature": "3rvQJW9BF4LLMrqxP6J9F6Vx8GVLUxdBf6Qd9eK95H2RQ3mS97nSQypGWGQatrP7LnDnbsMVYZ2Fj6DBLaQkBSUB",
    "signableEntity": {
      "routeId": "basic-api",
      "duration": 3600,
      "microUnitPrice": 100000,
      "validUntilUnixTimeStamp": 1683456789,
      "rateLimiters": [
        {
          "$type": "CallCount",
          "Count": 100
        }
      ]
    }
  },
  "requestedNanosubscriptionUTCStartTime": 1683457000
}

Purchase Instruction Response

{
  "stellarTransaction": "AAAAAI5BbQ/...",
  "authorisationToSign": "e7QeBQ4r...",
  "transactionSignature": "q5JlXQtRRs..."
}

3.2 Complete Purchase

POST /apicharge/nanosubscription/Purchase
Content-Type: application/json

{
  "stellarTransaction": "AAAAAI5BbQ/...",
  "authorisationToSign": "e7QeBQ4r...",
  "transactionSignature": "q5JlXQtRRs...",
  "authorisationSignature": "aFqTi2D..."
}

Access Token Response

{
  "signableEntity": {
    "signingPubkey": "GATCBZKXPNCVBKY5KLXSWLNUAXMUPARGW5JBSP75XYU6P3AK4JUMNXQ5",
    "signature": "J8KpLzrDCF7Y4kqt9DLZLsCNapQ7SiwsCXf6EPfCxmD2kZEhf9m2LjNPFSiYpRj2Y9TUKJSgNr9ivLnJdjwwMRDk",
    "signableEntity": {
      "routeId": "basic-api",
      "createdUnixTimeStamp": 1683457100,
      "expirationUnixTimeStamp": 1683460700,
      "nonce": 7283947621,
      "accountId": "GBXDGHXCQVZUDDD4NNGBOGCXYQFKNBPIMJWW7GMUCQ2OJCPO7B3GIXWA",
      "rateLimiters": [
        {
          "$type": "CallCount",
          "Count": 100
        }
      ]
    }
  }
}

The completed purchase results in an access token that the client can use to access the specified route. For detailed information about the purchase process, see the Purchase Flow page.

Step 4: Using the Service

With the access token in hand, the client can now access the purchased service by including the token in their requests.

Access Token Usage

The access token can be included in requests in one of three ways:

As an HTTP header: apicharge: {URL-encoded token}
As a cookie: apicharge={URL-encoded token}
As a URL-encoded query parameter (not recommended for production): ?apicharge={URL-encoded token}

Example Request with Token

GET /api/basic/data
Host: example.com
apicharge: eyJzaWduaW5nUHVia2V5IjoiR0... (URL-encoded token)

The server validates the token, enforces rate limits, and processes the request according to the purchased quality of service parameters. For detailed information about the authentication flow, see the Authentication Flow page.

Protocol Security

ApiCharge's protocol is designed with security at its core:

Cryptographic Signatures: All quotes and access tokens are digitally signed using ED25519
Blockchain Verification: Purchases are verified by the Stellar blockchain's Soroban contracts
Temporal Constraints: Quotes and tokens have explicit expiration times
Nonce Protection: Random nonces are included to prevent replay attacks
TLS Encryption: All communications should use HTTPS in production

Security Note: Always use HTTPS in production environments to protect token transmission and prevent man-in-the-middle attacks.

Client Implementation

To implement the ApiCharge protocol, clients need to:

Generate or manage an ED25519 key pair (using Stellar libraries)
Make HTTP requests to the ApiCharge endpoints
Parse and process JSON responses
Sign data using the Stellar SDK
Store and manage access tokens
Include tokens in subsequent API requests

ApiCharge provides client libraries for various platforms to simplify implementation:

.NET/C#: Available in the ApiChargeClient namespace
JavaScript/TypeScript: Available as an npm package
Python: Available as a pip package

Protocol Evolution

The ApiCharge protocol is designed for backward compatibility as new features are added:

All messages include type discriminators for polymorphic deserialization
New fields are added in a way that allows older clients to ignore them
Version information is included in access tokens to support multi-version deployments

Future protocol enhancements may include:

Support for subscription renewals without requiring new purchases
Advanced quota transfer mechanisms between subscribers
Delegated authorization for multi-tenant scenarios

Next Steps

To dive deeper into the protocol details, explore:

Authentication Flow - How access tokens are validated and enforced
Purchase Flow - Detailed walkthrough of the purchase process

Menu

Navigation

Getting Started

Configuration

Routes

Rate Limiters

Protocol Overview