antikode/opensea-sdk

An Opensea SDK for PHP Development

1.6 2025-06-18 14:21 UTC

Requires

• php: ^7.3|^8.0
• guzzlehttp/guzzle: ^7.9
• illuminate/http: ^8.0|^9.0|^10.0
• illuminate/support: ^8.0|^9.0|^10.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• orchestra/testbench: ^6.0|^7.0|^8.0
• phpunit/phpunit: ^9.0

MIT

• Rafi Halilintar

README

A PHP/Laravel SDK for integrating with the OpenSea API to interact with NFT collections, assets, and marketplace data.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
  • Get Collection
  • Get Collection Statistics
  • Validate NFT Owner
  • Retrieve Listings
  • Retrieve Offers
• Response Format
• Testing
• Troubleshooting
• Contributing
• License

Features

• 🖼️ Retrieve detailed collection information
• 📊 Get real-time collection statistics (floor price, volume, etc.)
• ✅ Validate NFT ownership by wallet address and token ID
• 💰 Retrieve active listings for NFTs
• 🤝 Get current offers for NFTs
• 🔄 Standardized response format for all API calls
• 🧪 Comprehensive test suite

Requirements

• PHP 7.3 or higher
• Laravel 8.0+ (for Laravel integration)
• Guzzle HTTP 7.0+
• OpenSea API key

Installation

Install the package via Composer:

composer require antikode/opensea-sdk

Laravel Integration

If you're using Laravel 5.5+, the service provider will be automatically registered.

For Laravel < 5.5, you need to manually add the service provider to your config/app.php file:

'providers' => [
    // ...
    Antikode\Opensea\OpenseaServiceProvider::class,
],

Configuration

Publish Configuration

Publish the configuration file:

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

Environment Variables

Add the following variables to your .env file:

OPENSEA_APIKEY=your_api_key_here
OPENSEA_COLLECTION=your_default_collection_slug
OPENSE_ASSET_CONTRACT_ADDR=your_contract_address

• OPENSEA_APIKEY: Your OpenSea API key
• OPENSEA_COLLECTION: Default collection slug (optional)
• OPENSE_ASSET_CONTRACT_ADDR: Default contract address (optional)

Usage

Get Collection

Retrieve detailed information about an NFT collection, including real-time statistics such as floor price.

use Antikode\Opensea\Opensea;

// Using default collection from .env
$result = Opensea::getCollection();

// Or specify a collection
$result = Opensea::getCollection('azuki');

// Using snake_case alias
$result = Opensea::get_collection('azuki');

Get Collection Statistics

Fetch statistics for a specific collection, including real-time floor price data.

use Antikode\Opensea\Opensea;

// Using default collection from .env
$result = Opensea::getCollectionStats();

// Or specify a collection
$result = Opensea::getCollectionStats('boredapeyachtclub');

// Using snake_case alias
$result = Opensea::get_collection_stat('boredapeyachtclub');

Validate NFT Owner

Verify if a wallet address owns a specific NFT from a collection.

use Antikode\Opensea\Opensea;

// Validate ownership with wallet address, token ID, and collection
$wallet = '0x4f14d3d1D3D95cd54Aa2812cAC3ce729dD8CDcf0';
$tokenId = '123';
$collection = 'cryptopunks';

$result = Opensea::validateOwner($wallet, $tokenId, $collection);

// Using default collection from .env
$result = Opensea::validateOwner($wallet, $tokenId);

// Using snake_case alias
$result = Opensea::validate_owner($wallet, $tokenId, $collection);

Retrieve Listings

Get the latest order/listing information for a specific NFT. Returns order details if the NFT is currently listed for sale, otherwise returns an empty array.

use Antikode\Opensea\Opensea;

// Get listings for a specific token ID and contract address
$tokenId = '909';
$contractAddr = '0xd2f668a8461d6761115daf8aeb3cdf5f40c532c6';

$result = Opensea::getListings($tokenId, $contractAddr);

Note: This method only works for NFTs that are currently listed for sale.

Retrieve Offers

Get current offers for an NFT that is not currently listed for sale. Returns offer details if offers exist, otherwise returns an empty array.

use Antikode\Opensea\Opensea;

// Get offers for a specific token ID and contract address
$tokenId = '909';
$contractAddr = '0xd2f668a8461d6761115daf8aeb3cdf5f40c532c6';

$result = Opensea::getOffers($tokenId, $contractAddr);

Note: This method only works for NFTs that are NOT currently listed for sale.

Response Format

All methods return a standardized response format:

[
    'success' => true|false,  // Boolean indicating if the request was successful
    'code' => 200,            // HTTP status code
    'data' => [...]           // Response data or error message
]

Example successful response:

[
    'success' => true,
    'code' => 200,
    'data' => [
        'collection' => [
            'name' => 'Bored Ape Yacht Club',
            'description' => 'The Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs...',
            // ... more collection data
        ]
    ]
]

Example error response:

[
    'success' => false,
    'code' => 404,
    'data' => 'Collection not found'
]

Testing

This package includes comprehensive tests for all functions and uses GitHub Actions for continuous integration.

Running Tests

# Using composer script
composer test

# Or directly with PHPUnit
vendor/bin/phpunit

# Run specific test suites
vendor/bin/phpunit --testsuite Unit
vendor/bin/phpunit --testsuite Feature

# Run a specific test file
vendor/bin/phpunit tests/Unit/ResponseMessageTest.php

Test Structure

• Unit Tests: Tests for the core response formatting functionality
• Feature Tests: Tests for the OpenSea API integration methods

Continuous Integration

This package uses GitHub Actions for continuous integration testing. The workflow automatically runs tests on multiple PHP versions (7.3, 7.4, 8.0, 8.1, 8.2) for every push to the main branch and pull request. You can see the current build status at the top of this README.

Troubleshooting

API Key Issues

If you're getting authentication errors, ensure your OpenSea API key is correctly set in your .env file.

Rate Limiting

OpenSea API has rate limits. If you're making too many requests in a short period, you might get rate-limited. Implement appropriate caching strategies to reduce API calls.

Collection Not Found

Ensure you're using the correct collection slug. Collection slugs are case-sensitive and should match exactly as they appear in OpenSea URLs.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Coding Standards

This package follows the PSR-12 coding standard. We use PHP CS Fixer to enforce these standards, which is automatically checked on each pull request and push to the main branch.

To check your code locally before committing:

# Check coding standards without fixing
composer cs-check

# Fix coding standards issues
composer cs

Testing

Please write tests for any new functionality. Run the test suite to make sure your changes don't break existing functionality:

composer test

License

The MIT License (MIT). Please see License File for more information.