The ApiCharge Protocol
Protocol Flow
- Request Signed Quote: Client requests a signed Quote containing price, duration, and quality-of-service parameters for various service routes (RouteQuotes). ApiCharge returns a cryptographically signed Quote with a time-limited validity window.
- Purchase Instruction Request: Client requests a purchase instruction for a selected RouteQuote, usually a minutes or hours of a certain quality of service for a single route. ApiCharge prepares and returns a transaction for the payment platform's smart contract.
- Client Authorise Payment: Client signs the transaction (which contains the RouteQuote) and returns it to ApiCharge. ApiCharge submits the signed transaction to the payment platform.
- Payment Execution: The payment platform's smart contract verifies the quote authenticity, validates expiration, and transfers funds.
- ApiCharge Subscription Issuance: ApiCharge issues a signed ApiCharge Subscription containing the original service parameters (the RouteQuote).
- Service Use: Client creates AccessTokens from the ApiCharge Subscription (with client-controlled lifetimes) and requests service access by adding it to either a header or cookie. ApiCharge validates the AccessToken, enforces purchased quality-of-service parameters, and proxies the request to the service.
This protocol ensures cryptographic verification at every step, with the payment platform's smart contract serving as a trusted third party. The dual-signed tokens and client-controlled token lifetimes provide enhanced security, while the quote-based system ensures that service terms cannot be modified after purchase.
Why Use a Smart Contract?
The Soroban smart contract on the Stellar blockchain serves several critical functions in the ApiCharge protocol:
Verification Authority
The smart contract independently verifies that the quote being purchased was actually issued by the claimed service provider by validating cryptographic signatures. This prevents malicious actors from creating counterfeit quotes or modifying legitimate ones.
Temporal Validation
The contract ensures that quotes have not expired and that ApiCharge Subscriptions start when requested. This prevents replay attacks where an attacker might try to reuse old quotes or manipulate timing parameters.
Funds Disbursement
The contract automatically calculates fees, manages payment distribution, and ensures funds are sent to the correct recipients. This provides a trustworthy intermediary that neither client nor server can manipulate.
Immutable Transaction Record
All transactions are recorded on the Stellar blockchain, creating an immutable audit trail that can be used for dispute resolution, accounting, and compliance purposes.
Using a smart contract creates a trusted, neutral, programmatic intermediary that enforces the rules of the protocol without requiring trust in either the service provider or the client. This is essential for a micropayment system where traditional dispute resolution would be impractical due to the small transaction sizes.
The Role of Route Quotes
Route Quotes are cryptographically signed promises from service providers that establish the terms of service availability. They play several crucial security roles:
Price Stability Guarantee
By issuing time-limited quotes, ApiCharge ensures that both parties agree to the same price before any payment occurs. This creates a binding agreement between client and server that mitigates potential disputes and ensures fair transactions.
Service Quality Definition
Quotes specify quality of service parameters (rate limiters) that define what the client is purchasing. These parameters are cryptographically protected from tampering, ensuring that the server must honor its promises.
Anti-Replay Protection
Each quote has validity windows that prevent reuse of expired quotes. The smart contract verifies these timings, preventing attackers from replaying old quotes to get access at outdated prices.
Route Quotes ensure price transparency and stability even in a volatile cryptocurrency environment. Since ApiCharge Subscriptions typically last minutes rather than months, short-term price fluctuations have minimal impact, and the quote system further mitigates this by offering a guaranteed price window.
Multi-Layered Access Token Security
The ApiCharge protocol implements a sophisticated multi-layered token system that provides secure access while preventing token theft, sharing, or abuse:
Dual Signature Requirement
Access tokens require cryptographic signatures from both the server and client. This creates a cryptographic bond that proves mutual agreement to the terms and prevents third parties from forging valid tokens.
Tiered Token Expiration
The system uses a two-tier token approach: GrantedAccessTokens (long-lived tokens based on purchase duration) and AccessTokens (short-lived tokens derived from GrantedAccessTokens). This allows clients to limit exposure by using short-lived tokens while maintaining the ability to refresh access.
Client-Controlled Expiration
Clients can specify their own expiration times for AccessTokens (as long as they are shorter than the purchased ApiCharge Subscription). This allows clients to implement their own security policies and reduce risk in case of token compromise.
Embedded Service Parameters
Access tokens contain the original route quote details, making them self-contained. This ensures that service quality parameters are bound to the token and cannot be modified, even if the server changes its offerings after purchase.
This robust token system ensures that access rights are non-transferable, time-limited, and cryptographically verifiable. The ability to create short-lived access tokens from longer ApiCharge Subscriptions provides an optimal balance of convenience and security.
Currency Volatility Mitigation
While cryptocurrencies can be volatile, several aspects of the ApiCharge design minimize the impact of price fluctuations:
Optional Short Duration Transactions
ApiCharge Subscriptions can last minutes rather than months, meaning price volatility has minimal impact during a single transaction. This can reduce FX exposure.
Stablecoin Transactions
ApiCharge Subscriptions can be settled in EURC and USDC, meaning the amount you charge is the amount paid, no volatility involved.
Quote Validity Windows
Service providers can adjust the validity window of their quotes to match their comfort level with price volatility. During high volatility periods, they may offer shorter quote validity times to reduce exposure.
Stellar Ecosystem Benefits
The Stellar network offers lower volatility than many cryptocurrencies and has built-in decentralized exchange capabilities, making it possible to integrate with stablecoins for customers who prefer them without modifying the core protocol.
By combining short-duration transactions with a quote-based pricing system, ApiCharge creates a natural buffer against cryptocurrency volatility. This approach allows clients and providers to interact confidently without requiring complex risk management strategies.
Protection Against Common API Attacks
ApiCharge includes several mechanisms to protect both service providers and clients against common API security threats:
Rate Limiting and DDoS Protection
The rate limiter strategies are not just service quality definitions—they're also powerful security controls that prevent resource exhaustion attacks. By enforcing strict rate limits at multiple levels (calls, bytes, credits), ApiCharge naturally mitigates most denial of service attacks.
Replay Attack Prevention
The combination of time-limited tokens, nonces in Stellar transactions, and unique sequence numbers prevents replay attacks where an attacker might attempt to reuse previous authentication messages or tokens to gain unauthorized access.
Tamper-Evident Protocol
Every component of the transaction flow is cryptographically signed and verified, creating a tamper-evident protocol where modifications are immediately detectable. This protects against man-in-the-middle attacks and ensures data integrity throughout the process.
Token Isolation
Each ApiCharge Subscription is bound to a specific route with specific parameters, preventing token reuse across different services or privilege escalation attacks. This ensures that a compromise of one token cannot affect other services.
The security measures in ApiCharge are designed to work together, creating a defense-in-depth approach that protects against a wide range of potential threats without requiring complex external security infrastructure.
Non-Custodial Design
ApiCharge and StreamCharge implement a non-custodial architecture that offers significant security and regulatory benefits:
Client-Controlled Keys
Client applications (like StreamCharge) maintain their own private keys in secure storage, giving users full control over their funds. No third party, including ApiCharge itself, ever has access to user private keys or the ability to initiate transactions without user authorization.
Regulatory Compliance
The non-custodial nature of the system means client apps qualify for exemptions under many regulatory frameworks (including EU MiCAR regulations), reducing compliance complexity while maintaining high security standards.
No Central Points of Failure
The distributed nature of the system eliminates central points of failure that could be targeted by attackers. Even if ApiCharge infrastructure were compromised, attackers would have no access to user funds.
This non-custodial approach significantly reduces security risks compared to traditional payment systems while simplifying regulatory compliance, creating a more robust ecosystem for both providers and consumers.
Transaction Transparency and Auditability
The ApiCharge protocol leverages the transparent nature of blockchain technology to provide unprecedented levels of transaction transparency and auditability:
Immutable Transaction Records
All payment transactions and smart contract interactions are recorded on the Stellar blockchain, creating an immutable record that can be independently verified by any party, helping to resolve disputes and provide accountability.
Business Transparency
Service providers can offer customers unprecedented transparency regarding their transactions, with verifiable records of every access purchase. This creates trust in commercial relationships without requiring third-party verification.
Compliance Reporting
The transparent nature of blockchain transactions simplifies reporting for tax and regulatory compliance, with all transaction records easily exportable and verifiable against a public ledger.
This level of transaction transparency creates a more trustworthy ecosystem where all parties can independently verify the integrity of their interactions, reducing the need for centralized oversight while improving accountability.
Horizontal Scaling and Failover Security
ApiCharge includes sophisticated mechanisms to maintain security even in horizontally scaled deployments:
Load Balancer Hints
The access token includes a load balancer hint (virtual node ID) that ensures consistent routing to the same physical node, preventing rate limit bypassing in clustered deployments while maintaining high availability.
Distributed Rate Limiting
Rate limiting state is maintained both in-memory for performance and in distributed cache (Redis) for resilience, ensuring that rate limits remain enforced even during node failures or restarts.
Graceful Degradation
The system is designed to gracefully degrade during partial failures, with mechanisms to maintain security constraints even when operating in degraded modes, preventing security bypasses during recovery scenarios.
These scaling and failover security mechanisms ensure that ApiCharge maintains consistent security properties regardless of deployment size or temporary infrastructure failures, creating a reliable foundation for mission-critical applications.
Mitigating Man-in-the-Middle (MITM) Attacks
ApiCharge takes a pragmatic approach to mitigating man-in-the-middle attacks that could potentially intercept Quote requests or spoof responses:
Public Key in Domain
For enhanced security, service providers can use the first N characters of their Stellar public key in the domain name (e.g., GA3RQ7.apicharge.com). When clients access the server over TLS, this creates a binding between the domain certificate and the expected Stellar signing key.
Public Key in URL Path
An alternative approach is including the server's Stellar public key in the URL path (e.g., apicharge.com/api/GA3RQ7FWMT6INHS2R4KEKWENPYQOPLRNPYDAJFFRY5AUSD2GP6VG3OPY). While not a complete protection against DNS hijacking, this allows client applications to verify that the Quote signatures match the expected key.
Limited Financial Exposure
Even in the worst-case scenario where a MITM attack successfully intercepts the initial Quote request, the client's financial exposure is limited to a single small apicharge subscription payment. Subsequent access attempts would fail, as the attacker-signed token would be invalid on the legitimate server.
No Personal Data Exposure
The ApiCharge protocol does not transmit personal data within access tokens. Even if a MITM attack occurs, the attacker cannot harvest sensitive user information beyond the public Stellar account information used for payment.
By implementing these recommendations, ApiCharge administrators can significantly reduce the risk of MITM attacks while ensuring that even successful attacks have minimal impact. These protections, combined with standard TLS encryption, create a robust defense against sophisticated interception attempts.