Credits

Credits are the billing unit for all blockchain API operations. They are only consumed on successful requests.

Every response includes these headers so you can track usage in real time:

X-Credits-Used: 1
X-Credits-Balance: 949
X-Request-Id: uuid

The credit system works as follows:

• Each API account has a credit balance.
• Before executing a chargeable request, the API checks your balance.
• If your balance is less than the endpoint's cost, HTTP 402 is returned and InsufficientCreditsException is thrown.
• On success, the exact credit cost is deducted and reflected in the response headers.
• Free endpoints (0-credit) always execute regardless of balance.

When your account balance is lower than the endpoint's cost, the API returns HTTP 402 before the operation executes. The plugin throws InsufficientCreditsException with parsed $cost and $balance properties:

<?php
use Web3Sdk\Laravel\Facades\Web3Api;
use Web3Sdk\Laravel\Exceptions\InsufficientCreditsException;

try {
    $tx = Web3Api::contract()->write(
        contractAddress: '0xCONTRACT...',
        functionName:    'mint',
        args:            ['0xUSER...', 1],
        abi:             $abi,
        fromAddress:     '0xSENDER...',
        privateKey:      '0xKEY...',
    );
} catch (InsufficientCreditsException $e) {
    // $e->cost    => 10
    // $e->balance => 3
    logger()->warning('Insufficient credits', [
        'needed'  => $e->cost,
        'current' => $e->balance,
        'deficit' => $e->cost - $e->balance,
    ]);

    // Guide the user to purchase more
    $packages = Web3Api::packages()->list();
    // Show $packages to user
}

<?php
use Web3Sdk\Laravel\Facades\Web3Api;

$result = Web3Api::credits()->balance();

echo $result['balance'];   // 950
echo $result['user_id'];   // "uuid..."

You can also view your credit debit/credit history:

<?php
$history = Web3Api::credits()->history(page: 1, limit: 20, type: 'debit');

// Each entry:
// $entry['type']           => "debit"
// $entry['amount']         => -10
// $entry['balance_before'] => 960
// $entry['balance_after']  => 950
// $entry['endpoint']       => "/api/v1/transfer/native"
// $entry['created_at']     => "2024-06-01T12:00:00"

Credit packages are available via the Packages module. Use the checkout endpoint to generate a Stripe Checkout URL:

<?php
use Web3Sdk\Laravel\Facades\Web3Api;

// 1. List available packages
$packages = Web3Api::packages()->list();
// [
//   ['id' => 'uuid', 'name' => 'Starter', 'credits' => 10000, 'price' => 9.99, 'currency' => 'USD'],
//   ['id' => 'uuid', 'name' => 'Pro',     'credits' => 50000, 'price' => 39.99, ...],
// ]

// 2. Get a specific package
$package = Web3Api::packages()->get(packageId: 'uuid-of-package');

// 3. Create Stripe Checkout session (requires JWT auth)
$checkout = Web3Api::packages()->checkout(
    packageId:  'uuid-of-package',
    successUrl: 'https://myapp.com/credits/success',
    cancelUrl:  'https://myapp.com/credits/cancel',
);

// Redirect user to Stripe Checkout
return redirect($checkout['checkout_url']);
// $checkout['session_id'] => "cs_..."

Set a threshold to receive a notification when your balance drops below a value:

<?php
// Get notified when balance drops below 100 credits
Web3Api::credits()->setAlertThreshold(threshold: 100);

Buy packages in your provider dashboard. See the Credits module for the balance check API.