web3sdk/laravel

Laravel SDK for CryptoFluid — multi-chain blockchain operations via a simple PHP API.

Full docs: plugins.cryptofluid.xyz/laravel/docs/index.html

Requirements

Installation

composer require web3sdk/laravel

Laravel auto-discovers the service provider. No manual registration needed.

Publish the config file:

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

Configuration

Add to your .env:

WEB3_API_KEY=ak_live_your_key_here
WEB3_DEFAULT_NETWORK=polygon
WEB3_TIMEOUT=30

Supported networks: ethereum, polygon, bsc, arbitrum, optimism, avalanche

Authentication

All requests use the X-API-Key header, sent automatically from WEB3_API_KEY.

The API key is bound to a specific network at creation time. If your key is locked to polygon, all calls run on polygon regardless of the $network argument — unless you create a separate key for each network.

Usage

Facade

use Web3Sdk\Laravel\Facades\Web3Api;

$balance = Web3Api::balance()->getNative('0xYOUR_ADDRESS', 'polygon');

Dependency Injection

use Web3Sdk\Laravel\Web3ApiClient;

class MyService
{
    public function __construct(private Web3ApiClient $web3) {}

    public function getBalance(string $address): array
    {
        return $this->web3->balance()->getNative($address);
    }
}

Modules

All modules are accessed via the facade or injected client.

balance() — Native & Token Balances

// Native coin balance (ETH, MATIC, BNB…)
// Response: { address, balance, balance_wei, symbol, network }
Web3Api::balance()->getNative('0xADDRESS', 'polygon');

// ERC-20 token balance
// Response: { token_address, wallet_address, balance, balance_raw, decimals, symbol, network }
Web3Api::balance()->getToken('0xTOKEN', '0xWALLET', 'polygon');

// Batch native balances (5 credits)
// Response: { "0xAAA": "1.5", "0xBBB": "0.25" }
Web3Api::balance()->batch(['0xAAA', '0xBBB'], 'polygon');

// Batch ERC-20 balances (5 credits)
Web3Api::balance()->batchToken('0xTOKEN', ['0xAAA', '0xBBB'], 'polygon');

transfer() — Send Tokens (10 credits each)

Security: Never pass private keys from browser clients. Call from server-side only, with keys stored in env/secrets manager.

// Send native coin
// Response: { tx_hash, from, to, amount, network, explorer_url }
Web3Api::transfer()->native(
    fromAddress: '0xSENDER',
    privateKey:  '0xPRIVATE_KEY',
    toAddress:   '0xRECEIVER',
    amount:      '0.1',
    network:     'polygon',
);

// Send ERC-20 token
Web3Api::transfer()->token(
    tokenAddress: '0xUSDC',
    fromAddress:  '0xSENDER',
    privateKey:   '0xPRIVATE_KEY',
    toAddress:    '0xRECEIVER',
    amount:       '10.5',
    decimals:     6,
    network:      'polygon',
);

transactions() — Transaction History & Status

// Check status of a submitted tx (2 credits)
// Response: { hash, status, block_number, gas_used }
Web3Api::transactions()->status(txHash: '0xHASH', network: 'polygon');

// List all recorded transactions (2 credits)
Web3Api::transactions()->history(status: 'confirmed', type: 'native_transfer', page: 1, limit: 50);

// Raw on-chain transaction data (2 credits)
Web3Api::transactions()->onchain('0xHASH', 'polygon');

// Single stored transaction by internal UUID (2 credits)
Web3Api::transactions()->get('tx-uuid');

wallets() — Managed Wallets

// Create new managed wallet (5 credits)
// Response: { address, private_key, warning }
Web3Api::wallets()->create();

// List all wallets (free)
Web3Api::wallets()->list();

// Retrieve private key — API key auth only (free)
// Response: { address, private_key }
Web3Api::wallets()->privateKey('0xADDRESS');

// Delete wallet (free)
Web3Api::wallets()->delete('wallet-id');

nft() — ERC-721 NFTs (2 credits each)

// NFT metadata + owner
// Response: { contract_address, token_id, owner, token_uri, name, symbol, network }
Web3Api::nft()->info('0xCONTRACT', 42, 'polygon');

// Number of NFTs owned in a collection
// Response: { contract_address, owner, balance, network }
Web3Api::nft()->balance('0xCONTRACT', '0xOWNER', 'polygon');

// Transfer NFT (10 credits)
// Response: { tx_hash, from, to, amount, network, explorer_url }
Web3Api::nft()->transfer(
    contractAddress: '0xCONTRACT',
    fromAddress:     '0xSENDER',
    privateKey:      '0xKEY',
    toAddress:       '0xRECEIVER',
    tokenId:         42,
    network:         'polygon',
);

nft1155() — ERC-1155 Multi-Tokens (2 credits each)

// Single token balance
// Response: { contract_address, owner, token_id, balance, network }
Web3Api::nft1155()->balance('0xCONTRACT', '0xOWNER', 1, 'polygon');

// Batch balance for multiple token IDs
// Response: [ { token_id: "1", balance: 10 }, … ]
Web3Api::nft1155()->balanceBatch('0xCONTRACT', '0xOWNER', ['1', '2', '3'], 'polygon');

// Token metadata URI
// Response: { contract_address, token_id, uri, network }
Web3Api::nft1155()->uri('0xCONTRACT', 1, 'polygon');

// Transfer (10 credits)
Web3Api::nft1155()->transfer(
    contractAddress: '0xCONTRACT',
    fromAddress:     '0xSENDER',
    privateKey:      '0xKEY',
    toAddress:       '0xRECEIVER',
    tokenId:         1,
    amount:          5,
    network:         'polygon',
);

tokens() — ERC-20 Token Info & Approvals

// Token metadata (1 credit)
// Response: { contract_address, name, symbol, decimals, total_supply, network }
Web3Api::tokens()->info('0xUSDC', 'polygon');

// Check spending allowance (1 credit)
// Response: { token_address, owner, spender, allowance, allowance_raw, symbol, network }
Web3Api::tokens()->allowance('0xTOKEN', '0xOWNER', '0xSPENDER', 'polygon');

// Approve spender (10 credits)
// Response: { tx_hash, from, to, amount, network, explorer_url }
Web3Api::tokens()->approve(
    tokenAddress:   '0xUSDC',
    ownerAddress:   '0xOWNER',
    privateKey:     '0xKEY',
    spenderAddress: '0xROUTER',
    amount:         '1000.0',
    decimals:       6,
    network:        'polygon',
);

gas() — Gas Prices & Estimates (1 credit each)

// Live gas prices
// Response: { network, gas_price_wei, gas_price_gwei, fast_gwei, standard_gwei, slow_gwei }
Web3Api::gas()->price('polygon');

// Estimate transaction fee
// Response: { network, transfer_type, estimated_gas, gas_price_gwei, estimated_cost_eth, estimated_cost_usd }
Web3Api::gas()->estimate(
    type:        'token_transfer',
    fromAddress: '0xSENDER',
    toAddress:   '0xRECEIVER',
    network:     'polygon',
);

prices() — USD Prices (1 credit each)

// Native coin price
// Response: { network, price_usd, price_change_24h, source, cached_at }
Web3Api::prices()->native('ethereum');

// ERC-20 token price
// Response: { contract_address, symbol, price_usd, price_change_24h, market_cap_usd, source, cached_at }
Web3Api::prices()->token('0xUSDC', 'polygon');

// Batch token prices (1 credit total)
Web3Api::prices()->batch(['0xUSDC', '0xWETH'], 'polygon');

blocks() — Block Data (1 credit each)

// Latest block
// Response: { block_number, hash, timestamp, transaction_count, gas_used, gas_limit, network }
Web3Api::blocks()->latest('polygon');

// Block by number
Web3Api::blocks()->get(18000000, 'polygon');

contract() — Arbitrary Contract Calls (10 credits each)

// Read-only call (no gas)
// Response: { result: … }
Web3Api::contract()->read(
    contractAddress: '0xCONTRACT',
    functionName:    'balanceOf',
    functionArgs:    ['0xUSER'],
    abi:             [/* minimal ABI fragment */],
    network:         'polygon',
);

// State-changing call
// Response: { tx_hash, network }
Web3Api::contract()->write(
    contractAddress: '0xCONTRACT',
    functionName:    'transfer',
    functionArgs:    ['0xTO', '1000000000000000000'],
    abi:             [/* ABI */],
    fromAddress:     '0xSENDER',
    privateKey:      '0xKEY',
    network:         'polygon',
);

events() — On-Chain Event Logs (2 credits each)

// Contract events by name + block range
Web3Api::events()->getEvents(
    contractAddress: '0xCONTRACT',
    event:           'Transfer',
    fromBlock:       '0',
    toBlock:         'latest',
    network:         'polygon',
    limit:           100,
);

// All transfer events for a wallet
Web3Api::events()->addressTransfers(
    address:      '0xWALLET',
    tokenAddress: '0xUSDC',
    network:      'polygon',
    limit:        100,
);

credits() — Credit Balance (free)

// Response: { balance, total_purchased, total_used }
Web3Api::credits()->balance();

utils() — Address & ENS Utilities (1 credit each)

// Validate address + get EIP-55 checksum form
// Response: { address, is_valid, checksum_address }
Web3Api::utils()->validateAddress('0xADDRESS');

// Resolve ENS name → address
// Response: { name, address, network, cached }
Web3Api::utils()->resolveEns('vitalik.eth');

// Reverse lookup address → ENS name
// Response: { address, name, network }
Web3Api::utils()->lookupEns('0xd8dA...');

networks() — Supported Networks (free)

// List all supported networks
Web3Api::networks()->list();

// Single network by slug
Web3Api::networks()->get('polygon');

Error Handling

use Web3Sdk\Laravel\Exceptions\AuthException;
use Web3Sdk\Laravel\Exceptions\InsufficientCreditsException;
use Web3Sdk\Laravel\Exceptions\Web3ApiException;

try {
    $result = Web3Api::balance()->getNative('0xADDRESS', 'polygon');
} catch (InsufficientCreditsException $e) {
    // HTTP 402 — not enough credits
    // $e->cost    → credits required
    // $e->balance → credits you have
    Log::warning("Need {$e->cost} credits, have {$e->balance}");
} catch (AuthException $e) {
    // HTTP 401 — missing or invalid API key
    Log::error('Auth failed: ' . $e->getMessage());
} catch (Web3ApiException $e) {
    // Any other 4xx/5xx
    Log::error("API error {$e->statusCode}: " . $e->getMessage());
}

Credit Costs

License

MIT