jupiter 1.0.1

A robust, type-safe Dart SDK for interacting with the Jupiter Ultra API. Supports Solana transaction signing, order routing, execution, balances, and token shield info.

Jupiter Dart SDK

A robust, type-safe Dart SDK for interacting with the Jupiter Ultra API. The simplest and safest way to trade on Solana with support for transaction signing, order routing, execution, balances, and token shield info.

Documentation

• Setup Guide - Complete setup and configuration instructions
• API Documentation - Detailed API reference
• Error Reference - Comprehensive error handling guide
• FAQ - Frequently asked questions and solutions

Table of Contents

• Features
• Installation
• Quick Start
• Usage Examples
• Advanced Configuration
• Error Handling
• Testing
• Contributing
• License

Features

• Complete Ultra API Integration: All endpoints (order, execute, balances, shield)
• Real Transaction Signing: Solana versioned transaction support with keypair signing
• Type Safety: Full type-safe models with JSON serialization
• Environment Support: .env file integration for Flutter apps
• Dual Endpoints: Support for both free (lite-api.jup.ag) and paid (api.jup.ag) endpoints
• Error Handling: Comprehensive error handling with detailed messages
• Testing: Unit, mock, and integration tests included
• Examples: Complete examples for all major use cases

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  jupiter: ^1.0.0

Then run:

dart pub get

Quick Start

Set your environment variables:

export PRIVATE_KEY=your_base58_encoded_solana_private_key
export JUP_API_KEY=your_jupiter_api_key_optional

Here's a minimal example to get started:

See the example/ folder for full examples. Here is a minimal order and execute:

import 'package:jupiter/jupiter.dart';
import 'dart:io';

void main() async {
  final client = UltraApiClient(
    apiKey: Platform.environment['JUP_API_KEY'],
    privateKeyEnvVar: 'PRIVATE_KEY',
  );
  final taker = client.getPublicKey();
  final request = UltraOrderRequest(
    inputMint: 'So11111111111111111111111111111111111111112',
    outputMint: 'USDC111111111111111111111111111111111111111',
    amount: 1000,
    taker: taker,
  );
  try {
    final result = await client.orderAndExecute(request);
    print(result);
  } finally {
    client.close();
  }
}

Examples

You can find additional code examples in the example folder:

• example/order-and-execute/main.dart: Place an order and execute it immediately
• example/balances/main.dart: Fetch and display account balances
• example/shield/main.dart: Get token information and warnings

Run examples with:

dart example/order-and-execute/main.dart
dart example/balances/main.dart
dart example/shield/main.dart

Advanced Configuration

For detailed configuration options, see the Setup Guide.

Key features include:

• Custom HTTP client configuration
• Retry strategies
• Logging setup
• Environment configuration
• Test mode settings

Error Handling

The SDK provides comprehensive error handling. See the Error Reference for details on:

• Exception types and hierarchy
• Error patterns and best practices
• Recovery strategies
• Testing error scenarios

Testing

The SDK includes extensive testing support:

void main() {
  test('swap succeeds', () async {
    final mock = MockUltraApiClient();
    when(mock.orderAndExecute(any))
      .thenAnswer((_) => Future.value(successResponse));
    
    final result = await mock.orderAndExecute(request);
    expect(result.success, isTrue);
  });
}

For more testing examples, see the tests directory.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Key areas:

1. Bug reports and fixes
2. Feature requests and implementations
3. Documentation improvements
4. Example code additions

Support

Need help? Check these resources:

1. FAQ - Common questions and answers
2. API Documentation - Complete API reference
3. Setup Guide - Detailed setup instructions
4. GitHub Issues - Bug reports and feature requests
5. Discord Community - Real-time help

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Jupiter Protocol team for the excellent API
• Solana ecosystem contributors
• Our open source contributors

For a Flutter UI demonstration, see example/lib/main.dart.

Advanced Configuration

Client Configuration Options

final client = UltraApiClient(
  apiKey: 'your_api_key',
  privateKeyEnvVar: 'PRIVATE_KEY',
  // Optional configurations
  enableRetry: true,
  retryConfig: RetryConfig(
    maxAttempts: 3,
    initialDelay: Duration(milliseconds: 200),
  ),
  enableLogging: true,
  timeout: Duration(seconds: 30),
);

Custom Request Options

// Add custom headers
final result = await client.orderAndExecute(
  request,
  customHeaders: {'X-Custom-Header': 'value'},
);

// Configure request-specific timeout
final response = await client.getBalances(
  publicKey: address,
  timeout: Duration(seconds: 15),
);

Environment Configuration

Use a .env file for configuration:

PRIVATE_KEY=your_base58_encoded_private_key
JUP_API_KEY=your_jupiter_api_key

Load environment variables in your code:

import 'package:dotenv/dotenv.dart';

void main() {
  final env = DotEnv()..load();
  final client = UltraApiClient(
    apiKey: env['JUP_API_KEY'],
    privateKeyEnvVar: 'PRIVATE_KEY',
  );
}

Error Handling

The SDK provides comprehensive error handling with specific exception types:

try {
  final result = await client.orderAndExecute(request);
} on JupiterApiException catch (e) {
  // Handle API-specific errors
  print('API Error: ${e.message}');
  print('Status Code: ${e.statusCode}');
} on JupiterTransactionException catch (e) {
  // Handle transaction-related errors
  print('Transaction Error: ${e.message}');
  print('Transaction ID: ${e.signature}');
} on JupiterValidationException catch (e) {
  // Handle input validation errors
  print('Validation Error: ${e.message}');
} on JupiterException catch (e) {
  // Handle general SDK errors
  print('General Error: ${e.message}');
}

Common Error Scenarios

1. API Key Issues

try {
  await client.getOrder(request);
} on JupiterApiException catch (e) {
  if (e.statusCode == 401) {
    print('Invalid or missing API key');
  }
}

2. Transaction Errors

try {
  await client.execute(order);
} on JupiterTransactionException catch (e) {
  if (e.message.contains('insufficient funds')) {
    print('Not enough SOL for transaction fees');
  }
}

3. Network Issues

try {
  await client.getBalances(publicKey: address);
} on JupiterException catch (e) {
  if (e.message.contains('timeout')) {
    print('Network request timed out');
  }
}

Testing

Running Tests

# Run all tests
dart test

# Run specific test file
dart test test/ultra_api_client_test.dart

# Run tests with coverage
dart test --coverage coverage

Test Categories

• Unit Tests: Test individual components in isolation
• Integration Tests: Require real API key and Solana keypair
• Mock Tests: Use mock responses for API testing

Writing Tests

void main() {
  test('should create order successfully', () async {
    final client = UltraApiClient(
      apiKey: 'test_key',
      privateKeyEnvVar: 'TEST_KEY',
    );
    final request = UltraOrderRequest(/* ... */);
    final result = await client.getOrder(request);
    expect(result, isNotNull);
  });
}

Contributing

We welcome contributions! Please see our documentation for details:

• Development Guide - Setup and development workflow
• Release Guide - Publishing new versions
• Publishing Guide - pub.dev specific guidance

See the Python SDK for reference implementation: jup-python-sdk

Contribution Guidelines

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass
5. Submit a pull request

Code Style

We follow the Effective Dart style guide. Please ensure your code:

• Uses strong mode and strict type checking
• Is properly formatted (dart format)
• Passes static analysis (dart analyze)
• Includes documentation for public APIs

Documentation

API Reference

• API Documentation
• Jupiter Ultra API Docs

Guides

• Quick Start Guide
• Development Guide
• Release Process
• Publishing Guide

Examples

Complete examples are available in the example directory:

• Order and Execute
• Balances
• Shield
• Flutter UI Demo

License

MIT License - see the LICENSE file for details.