fix: Fixes prompted by lite-api.jup.ag being deprecated on 31st January 2026

[dangow3]

Branch Summary: fix/update_to_api_response

Overview

This branch updates the Jupiter Swap API Client to align with recent Jupiter API changes, focusing on mandatory API key authentication, enhanced error handling, and expanded response data structures.

Branch: fix/update_to_api_response
Base: main
Commits: 6 commits ahead of main
Files Changed: 8 files (+80 insertions, -25 deletions)

---

Key Changes

1. Mandatory API Key Authentication 🔑

Breaking Change: API key is now required for all requests.

• Updated JupiterSwapApiClient constructor to require an api_key parameter
• API key is automatically included as x-api-key header in all HTTP requests
• Updated all usage examples in README and example code

Before:

let client = JupiterSwapApiClient::new("https://quote-api.jup.ag/v6".to_string());

After:

let client = JupiterSwapApiClient::new(
    "https://quote-api.jup.ag/v6".to_string(),
    "your-api-key".to_string()
);

Files Modified:

• jupiter-swap-api-client/src/lib.rs - Added api_key field to struct and header injection
• example/src/main.rs - Updated to read API key from JUPITER_API_KEY env variable
• README.md - Added API key documentation and usage examples

---

2. Enhanced Error Handling & Logging 🔍

Added comprehensive logging and improved error diagnostics for API responses.

Changes:

• Added tracing dependency for structured logging
• Introduced new JsonParseError variant to ClientError enum
• Enhanced check_status_code_and_deserialize() to:
  • Capture raw response text before deserialization
  • Log response length and full JSON at debug level
  • Provide detailed error context on deserialization failures

Benefits:

• Easier debugging of API integration issues
• Better visibility into Jupiter API responses
• Clearer error messages when response format changes

Files Modified:

• jupiter-swap-api-client/Cargo.toml - Added tracing = "0.1" dependency
• jupiter-swap-api-client/src/lib.rs - Implemented enhanced logging

---

3. Updated SwapInfo Response Structure 📊

Extended SwapInfo struct to include additional fields returned by Jupiter API v6.

New Fields:

• fee_amount: Option<String> - Optional fee amount charged by the AMM
• fee_mint: Option<String> - Optional fee token mint (rarely populated)
• out_amount_after_slippage: u64 - Output amount accounting for configured slippage

Key Notes:

• fee_amount and fee_mint are optional as Jupiter API doesn't always return them
• These fields use Option<String> instead of deserialization helpers for flexibility
• out_amount_after_slippage is required and uses field_as_string serialization

Files Modified:

• jupiter-swap-api-client/src/quote.rs - Updated main SwapInfo struct
• jupiter-swap-api-client/src/route_plan_with_metadata.rs - Updated route planning SwapInfo
• jupiter-swap-api-client/src/serde_helpers/option_field_as_string.rs - Improved empty string handling

---

4. Documentation & Code Quality Improvements 📝

• README Updates:

  • Added "API Key Requirement" section with setup instructions
  • Updated all code examples to include API key parameter
  • Added reference to Jupiter developer portal for API key acquisition

• Code Comments:

  • Improved clarity in SwapInfo field descriptions
  • Added context about when optional fields are populated
  • Fixed formatting inconsistencies

• Environment Variables:

  • Documented JUPITER_API_KEY environment variable
  • Updated example code to read from environment

---

Detailed Commit History

443715e - fix: Correct formatting in debug log for Jupiter API raw response in lib.rs
2f071d5 - feat: Add tracing dependency and enhance error handling with detailed logging
7cd8400 - feat: Require API key for JupiterSwapApiClient and update usage examples
25d3230 - refactor: Update fee_amount and fee_token_mint to use option_field_as_string
2e47279 - fix: Enhance SwapInfo struct with additional fields (fee details, out_amount_after_slippage)
fb95cfa - clean up

---

Migration Guide

For Existing Users

Required Changes:

1. Update Constructor Calls:

   // Old
   let client = JupiterSwapApiClient::new(base_url);
   
   // New
   let client = JupiterSwapApiClient::new(base_url, api_key);

2. Obtain API Key:

   • Visit Jupiter Developer Portal
   • Generate an API key
   • Store securely in environment variables or configuration

3. Update Environment Variables:

   export JUPITER_API_KEY="your-api-key"

4. Update Code to Handle New Fields:

   // SwapInfo now includes:
   quote.swap_info.fee_amount; // Option<String>
   quote.swap_info.fee_mint; // Option<String>
   quote.swap_info.out_amount_after_slippage; // u64

Optional Changes:

• Enable tracing subscriber to capture detailed API logs
• Update error handling to account for new JsonParseError variant

---

Testing Recommendations

1. API Key Validation:

   • Verify requests fail gracefully with invalid/missing API key
   • Confirm x-api-key header is present in all requests

2. Response Parsing:

   • Test with quotes that include fee information
   • Test with quotes where fees are absent (ensure no deserialization errors)
   • Verify out_amount_after_slippage calculation

3. Error Handling:

   • Trigger JSON parse errors to verify logging output
   • Check tracing logs contain full response bodies for debugging

4. Backward Compatibility:

   • Ensure existing integrations work with updated SwapInfo structure
   • Verify optional fields don't break existing logic

---

Dependencies Added

Dependency	Version	Purpose
tracing	0.1	Structured logging for API responses and error diagnostics

---

Breaking Changes Summary

✅ API Key Required - All instantiations of JupiterSwapApiClient must now provide an API key
✅ Constructor Signature Changed - new() method now takes two parameters instead of one
⚠️ SwapInfo Extended - New fields added (backward compatible for deserialization)

---

Related Resources

• Jupiter API v6 Documentation
• Jupiter Developer Portal
• Self-Hosted API Guide
• Paid Hosted APIs

---

Authors & Contributors

This branch includes contributions addressing Jupiter API v6 updates and authentication requirements.

---

Next Steps

• Merge to main after testing
• Update version in Cargo.toml (bump minor version for breaking change)
• Publish to crates.io (if applicable)
• Notify downstream consumers of breaking changes
• Update integration tests in consuming projects

---

Last Updated: January 23, 2026