README

The official Laravel SDK for Volta — AI billing, handled.

Requirements

PHP 8.2+
Laravel 10, 11, or 12

Installation

composer require darknautica/volta-php

Publish the config:

php artisan vendor:publish --tag=volta-config

Add to your .env:

VOLTA_APP_KEY=your-app-key-here
VOLTA_BASE_URL=https://volta.test

Quick Start

Three lines to add billing to any AI endpoint:

use DarkNautica\Volta\Facades\Volta;

// Check before calling AI
if (!Volta::hasAccess($user->id)) {
    return response()->json(['error' => 'Insufficient credits'], 402);
}

// Make your AI call here...

// Deduct after success
Volta::charge($user->id, 1);

Middleware

Protect entire routes automatically:

// Requires 1 credit (default)
Route::post('/generate', [AIController::class, 'generate'])
    ->middleware('volta.gate');

// Requires 3 credits, specific model
Route::post('/analyze', [AIController::class, 'analyze'])
    ->middleware('volta.gate:3,gpt-4');

The middleware resolves the user automatically:

$request->volta_user_id if set explicitly
$request->user()->id if authenticated
Falls back to request IP for anonymous users

Blade Directives

{{-- Show balance --}}
<span>@voltaBalance($user->id) credits remaining</span>

{{-- Conditional content --}}
@voltaHasAccess($user->id, 1)
    <button>Generate</button>
@endvoltaHasAccess

@voltaNoAccess($user->id, 1)
    <a href="/billing">Buy more credits</a>
@endvoltaNoAccess

{{-- Embed billing portal --}}
<iframe src="@voltaPortalUrl($user->id)" width="100%" height="600"></iframe>

Available Methods

Method	Description
`Volta::charge($userId, $credits, $model?)`	Deduct credits. Throws on failure.
`Volta::hasAccess($userId, $credits?)`	Check access. Always returns bool.
`Volta::balance($userId)`	Get credit balance.
`Volta::topUp($userId, $credits)`	Add credits to a user.
`Volta::usage($userId)`	Get usage history array.
`Volta::portalUrl($userId, $options?)`	Get signed billing portal URL.

Testing Connection

php artisan volta:test

This will verify your API key, test connectivity, and display account info.

Error Handling

use DarkNautica\Volta\Exceptions\InsufficientCreditsException;
use DarkNautica\Volta\Exceptions\RateLimitExceededException;

try {
    Volta::charge($user->id, 1);
} catch (InsufficientCreditsException $e) {
    return response()->json(['error' => 'Not enough credits'], 402);
} catch (RateLimitExceededException $e) {
    return response()->json(['error' => 'Slow down', 'retry_after' => $e->retryAfter], 429);
}

Fail Silently Mode

Set VOLTA_FAIL_SILENTLY=true in .env to prevent Volta errors from crashing your app. When enabled:

hasAccess() returns false
balance() returns 0
charge() returns false

This is useful for apps that should degrade gracefully if Volta is unreachable.

Configuration

Env Variable	Default	Description
`VOLTA_APP_KEY`	(required)	Your Volta API key
`VOLTA_BASE_URL`	`https://volta.test`	Volta API base URL
`VOLTA_TIMEOUT`	`10`	HTTP timeout in seconds
`VOLTA_FAIL_SILENTLY`	`false`	Suppress exceptions, return safe defaults
`VOLTA_CACHE_TTL`	`30`	Balance cache duration in seconds (0 to disable)

License

MIT

darknautica / volta-php

Maintainers

Package info

Statistics

Security