Download the PHP package asciisd/pelican without Composer

Pelican Laravel SDK

Latest Version on Packagist Tests Total Downloads License PHP Version

A modern, clean Laravel package for integrating with the CopyTrade (Pelican) API. Built with SOLID principles, type-safety, and developer experience in mind.

Features

• Full API coverage — every endpoint in the CopyTrade API collection is available as a typed service method
• Built-in OAuth2 login — Authorization Code with PKCE, driven entirely server-side (no browser needed)
• Single Sign-On (SSO) — OpenID Connect redirect login, callback, session, and federated logout
• Type-safe DTOs — fully typed data transfer objects for all API responses
• Interface-based services — easy mocking and testing
• Laravel-native — service container bindings, facade, config publishing, and package auto-discovery
• Comprehensive error handling — specific exceptions for different error types

Requirements

• PHP 8.2 or higher
• Laravel 12.0 or 13.0

Installation

Install the package via Composer from Packagist:

The package is auto-discovered by Laravel — no manual provider registration needed.

Configuration

Publish the configuration file (optional — sensible defaults are provided):

Environment Variables

Quick Start

Every API area is exposed as a service off the facade:

Authentication

The CopyTrade API uses the OAuth2 Authorization Code flow with PKCE. The package drives the whole flow for you — log in with an email and password and get a token back in one call.

Login with credentials (recommended)

Behind the scenes the package walks the Pelican identity server's hosted login page server-side (authorize → login form → authorization code → token exchange), so no browser, iframe, or callback route is needed.

A failed login (wrong credentials, misconfigured client, etc.) throws an Asciisd\Copytrade\Exceptions\AuthenticationException:

Storing and reusing the token

TokenDTO serializes cleanly, so you can cache it and refresh it when it expires:

Revoke a token when you are done with it:

Browser-based login (advanced)

If you prefer to send the user to Pelican's hosted login page in their own browser, generate an authorization request, store its state and PKCE verifier in the session, and redirect:

Then validate the returned state on your callback route before exchanging the one-time authorization code:

The redirect URI must exactly match a redirect URI registered for the Pelican OAuth client. Note: the default public pelican client only allows its custom scheme callback (pelican://authenticated), which is why the credential-based login() above is the recommended path for headless / API use. For a browser login that signs the user into your app, use Single Sign-On.

Single Sign-On (SSO)

SSO sends the user to Pelican's identity server in their browser, then brings them back to your Laravel app with an access token and OpenID Connect claims. Use this when you want "Login with CopyTrade" instead of collecting a Pelican email and password yourself.

Copytrade::sso() wraps the OAuth building blocks (authorizationRequest() / exchangeCode()) into a drop-in flow: start URL, callback, session, token refresh, and federated logout.

1. Register an OAuth client

The public pelican client cannot complete a browser SSO flow — its only allowed callback is pelican://authenticated. Ask Pelican / CopyTrade to register your application with:

Then point the package at that client:

offline_access is what makes Pelican issue a refresh token so the SSO session can outlive the access token.

If you enable the package routes and leave COPYTRADE_CALLBACK_URL empty (or set to the custom pelican:// scheme), the package uses route('copytrade.sso.callback') as the redirect URI. That URL must still be registered on the OAuth client.

2. Enable the package routes (recommended)

With COPYTRADE_SSO_ENABLED=true the package registers:

Change the path with COPYTRADE_SSO_PREFIX if you need a different prefix.

Wire them in your UI:

Optional query parameters on the start URL:

• intended — path to return to after a successful login. Pass a same-app relative path such as /dashboard. Do not pass an absolute URL (https://… or //…); Laravel will redirect there after login.
• login_hint — pre-fill the email on Pelican's hosted login page

?local=1 on the logout URL skips federated logout and only clears the local SSO session. Prefer POST for logout so the request is CSRF-protected.

After a failed callback the user is sent to COPYTRADE_SSO_REDIRECT_ON_ERROR with a flashed copytrade_sso_error message.

3. Map the Pelican identity to a local user

The package does not call Auth::login() for you — host apps own their user model. Listen for SsoAuthenticated and create or look up the local account:

$event->user is a UserInfoDTO with profileId, sub, email, name, givenName, familyName, and emailVerified. $event->token is the TokenDTO you can cache per local user if you need the API from a queue or a later request.

4. Use the SSO token for API calls

You can drive the same flow without the package routes:

If you disable the package routes, COPYTRADE_CALLBACK_URL must be an http:// or https:// URL that matches the redirect URI registered on the OAuth client. The custom pelican://authenticated scheme is rejected for SSO.

Token scoping

withToken() returns token-scoped copies of the services and never mutates the shared singletons, so it is safe to work with several accounts side by side:

If COPYTRADE_ACCESS_TOKEN is set, that token is applied to every service automatically and withToken() is only needed for overrides.

API Reference

ProfileService — Copytrade::profiles()

Manage user profiles and account information.

ServerService — Copytrade::servers()

Use the returned server codes when creating copier or strategy connections.

StrategyService — Copytrade::strategies()

Manage trading strategies, stats, search, signals, and strategy images.

CopierService — Copytrade::copiers()

Manage copiers (follower accounts), copy settings, copier signals, and copier images.

SectionService — Copytrade::sections()

Retrieve the "Discover" sections used to browse featured strategies.

Endpoint Coverage

Every request in the CopyTrade API Postman collection maps to a package method:

Data Transfer Objects

All API responses are wrapped in DTOs. Every DTO exposes typed properties for the common fields plus a rawData array with the complete, untouched API response, and serializes with toArray() / json_encode():

Error Handling

The package throws specific exception types, all extending CopytradeException:

Testing Your Application

All services are bound to interfaces in the container, so they are trivial to mock in your application tests:

Because the services use Laravel's HTTP client internally, you can also fake at the HTTP layer:

Running the package test suite

Architecture

Each service handles exactly one API domain, every service is consumed through its interface, and token scoping is immutable (withToken() returns a copy), so a token from one request can never leak into another.

License

This package is open-sourced software licensed under the MIT license.