API Documentation

Quick Start

Get started with our API in minutes. Create an account to get your API key.

Get Free API Key

Base URL

https://binbase.su/api/v1

Authentication

Include your API key in the request header or as a query parameter:

Header (Recommended)

X-API-Key: your_api_key

Query Parameter

https://binbase.su/api/v1/lookup/424242?api_key=your_api_key

Endpoints

GET /api/v1/lookup/{bin}

Look up BIN/IIN information including card brand, type, level, issuing bank and country.

Parameters

bin	6-8 digit BIN number (path parameter, required)

Example Request

curl -H "X-API-Key: your_api_key" https://binbase.su/api/v1/lookup/424242

Success Response (200)

{
  "success": true,
  "data": {
    "bin": "424242",
    "brand": "VISA",
    "type": "DEBIT",
    "level": "CLASSIC",
    "bank": {
      "name": "Example Bank",
      "phone": "+1-800-555-0123",
      "url": "www.examplebank.com"
    },
    "country": {
      "code": "US",
      "name": "United States"
    }
  }
}

Error Response (404)

{
  "success": false,
  "error": "BIN not found."
}

Rate Limits

Rate limits depend on your API tier. When a premium tier's limits are exhausted, requests automatically fall back to the free tier's limits instead of being blocked.

Tier	Daily Limit	Monthly Limit	Price
Free	Unlimited	Unlimited	Free
Premium	100,000/day	3,000,000/month	$2.00/mo

Rate Limit Headers

Every API response includes rate limit headers so you can track your usage:

Header	Description
X-RateLimit-Limit-Day	Your daily request limit
X-RateLimit-Remaining-Day	Remaining requests today
X-RateLimit-Limit-Month	Your monthly request limit
X-RateLimit-Remaining-Month	Remaining requests this month
X-RateLimit-Tier	Your current API tier name

Note: Headers with "Unlimited" limits are omitted from the response.

Premium Expiry

Premium API keys have an expiration date. When a premium key expires, it is automatically downgraded to the free tier. Your API key itself remains the same — only the tier and limits change. You can check your key's expiry date on your API Key Management page.

Error Codes

Code	Description
400	Invalid BIN format — must be 6-8 digits
401	Invalid or missing API key
404	BIN not found in our database
429	Rate limit exceeded on all tiers — retry tomorrow
503	API temporarily disabled by administrator

Code Examples

curl -X GET "https://binbase.su/api/v1/lookup/424242" \
  -H "X-API-Key: your_api_key"

# Response headers include:
# X-RateLimit-Limit-Day: 999
# X-RateLimit-Remaining-Day: 998
# X-RateLimit-Tier: Premium

<?php
$apiKey = 'your_api_key';
$bin    = '424242';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://binbase.su/api/v1/lookup/' . $bin);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);

$response   = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers    = substr($response, 0, $headerSize);
$body       = substr($response, $headerSize);
$httpCode   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($body, true);

// Check rate limit headers
foreach (explode("\r\n", $headers) as $line) {
    if (stripos($line, 'X-RateLimit') === 0) {
        echo $line . "\n";
    }
}

if ($httpCode === 200 && $data['success']) {
    echo "Brand: " . $data['data']['brand'] . "\n";
    echo "Type: "  . $data['data']['type'] . "\n";
    echo "Bank: "  . $data['data']['bank']['name'] . "\n";
    echo "Country: " . $data['data']['country']['name'] . "\n";
} else {
    echo "Error: " . ($data['error'] ?? 'Unknown') . "\n";
}

import requests

response = requests.get(
    'https://binbase.su/api/v1/lookup/424242',
    headers={'X-API-Key': 'your_api_key'}
)

# Check rate limit headers
print('Remaining today:', response.headers.get('X-RateLimit-Remaining-Day'))
print('Tier:', response.headers.get('X-RateLimit-Tier'))

data = response.json()
if data.get('success'):
    print(data['data']['brand'], data['data']['type'])
else:
    print('Error:', data.get('error'))

const response = await fetch('https://binbase.su/api/v1/lookup/424242', {
  headers: { 'X-API-Key': 'your_api_key' }
});

// Check rate limit headers
console.log('Remaining:', response.headers.get('X-RateLimit-Remaining-Day'));
console.log('Tier:', response.headers.get('X-RateLimit-Tier'));

const data = await response.json();
if (data.success) {
  console.log(data.data);
} else {
  console.error(data.error);
}

Full PHP Integration Script

A ready-to-use PHP class for integrating BinBase.su into your project:

<?php
/**
 * BinBase.su API Client
 * Usage: $client = new BinBaseClient('your_api_key');
 *        $result = $client->lookup('424242');
 */
class BinBaseClient {
    private string $apiKey;
    private string $baseUrl = 'https://binbase.su/api/v1';
    private array  $lastHeaders = [];

    public function __construct(string $apiKey) {
        $this->apiKey = $apiKey;
    }

    public function lookup(string $bin): ?array {
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL            => $this->baseUrl . '/lookup/' . urlencode($bin),
            CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $this->apiKey],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER         => true,
            CURLOPT_TIMEOUT        => 10,
        ]);

        $response   = curl_exec($ch);
        $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $headers    = substr($response, 0, $headerSize);
        $body       = substr($response, $headerSize);
        curl_close($ch);

        $this->parseHeaders($headers);
        return json_decode($body, true);
    }

    public function getRemainingDaily(): ?int {
        return $this->lastHeaders['X-RateLimit-Remaining-Day'] ?? null;
    }

    public function getTier(): ?string {
        return $this->lastHeaders['X-RateLimit-Tier'] ?? null;
    }

    private function parseHeaders(string $raw): void {
        $this->lastHeaders = [];
        foreach (explode("\r\n", $raw) as $line) {
            if (str_contains($line, ':')) {
                [$key, $val] = explode(':', $line, 2);
                $this->lastHeaders[trim($key)] = trim($val);
            }
        }
    }
}

// --- Example usage ---
$client = new BinBaseClient('your_api_key');
$result = $client->lookup('424242');

if ($result && ($result['success'] ?? false)) {
    $d = $result['data'];
    echo "BIN {$d['bin']}: {$d['brand']} {$d['type']} ({$d['level']})\n";
    echo "Bank: {$d['bank']['name']}\n";
    echo "Country: {$d['country']['name']} ({$d['country']['code']})\n";
    echo "Remaining today: " . $client->getRemainingDaily() . "\n";
    echo "Tier: " . $client->getTier() . "\n";
} else {
    echo "Error: " . ($result['error'] ?? 'Request failed') . "\n";
}