Table of Contents

Overview Versioning Policy Backward Compatibility V1 to V2 Migration Endpoint Changes Response Format Updates Deprecation Timeline Breaking Changes Step-by-Step Migration Support & Resources

API Documentation

API Migration Guide — Upgrading Between Versions

Plan and execute smooth API version upgrades. Understand breaking changes, deprecation timelines, and best practices for migrating between Smart Money API versions.

Published March 21, 2026 • 16 min read • Advanced

Migration Overview

Smart Money API is actively developed with regular updates. This guide covers version management, breaking changes, and how to migrate your integration with zero downtime.

Migration key principles:

Semantic Versioning — MAJOR.MINOR.PATCH format strictly followed
Long-Term Support — Previous major version supported for 24+ months
Deprecation Warnings — 6-month advance notice on all breaking changes
Parallel Versions — Run v1 and v2 simultaneously during migration
Automated Testing — Test suite compatibility tools provided

Current Status: v1 (current), v2 (beta, general availability Q2 2026). v1 supported until Q1 2028.

Versioning Policy

Semantic Versioning

Version Format
API Version: MAJOR.MINOR.PATCH
Example: 2.1.3
MAJOR (2) - Breaking changes, new architecture
MINOR (1) - Backward-compatible features
PATCH (3) - Bug fixes, security updates

Version Release Cycle

Phase	Duration	Characteristics
Alpha	2-4 weeks	Heavy breaking changes, testing only
Beta	4-8 weeks	Mostly stable, community feedback
Release Candidate	2-4 weeks	Production-ready, final polish
General Availability	24+ months	Full production support

Get your API key in 30 seconds

Ready to build? Grab a free API key (200 calls/day, no card) and start pulling live whale, funding and on-chain data.

Get your API key →

Backward Compatibility

Version Compatibility

Within a major version, you can always upgrade to newer minor/patch versions safely:

Endpoint URLs — Remain unchanged
Required Fields — Never removed (only new optional fields added)
HTTP Status Codes — Preserved for existing scenarios
Response Structure — Core fields remain identical
Authentication — No changes to auth mechanisms

Graceful Deprecation

Deprecation Timeline
// Month 1: Announce deprecation
// Feature marked with Deprecation header
Deprecation: version="2.2", sunset="2026-09-01"
// Month 3-6: Active deprecation period
// API returns warnings but still works
X-Deprecation-Warning: This endpoint will be removed on 2026-09-01
// Month 6: Final removal
// Endpoint returns 410 Gone
HTTP/1.1 410 Gone

V1 to V2 Migration

Major Changes

REST API Redesign — Cleaner resource endpoints
Response Format — Consistent wrapping, better error handling
Authentication — OAuth 2.0 support added (API keys still work)
Rate Limiting — Improved granularity and clarity
Webhooks — Redesigned event format and signing

Endpoint Mapping

v1 Endpoint	v2 Endpoint	Changes
GET /whales	GET /v2/whales/tracking	Reorganized, added filtering
GET /funding	GET /v2/derivatives/funding-heatmap	Exchange parameter required
GET /positions	GET /v2/derivatives/positions	New aggregation options

Endpoint Changes

Request Parameter Changes

V1 Request
// V1: Funding rates
GET /v1/funding?symbol=BTCUSDT&exchange=binance

V2 Request
// V2: Same data, clearer structure
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Response Format Updates

V1 Response Structure

V1 Format
{
  "status": "success",
  "data": {
    "symbol": "BTCUSDT",
    "funding": 0.0001
  }
}

V2 Response Structure

V2 Format
{
  "data": {
    "symbol": "BTCUSDT",
    "funding_rate": 0.0001
  },
  "_meta": {
    "request_id": "req_abc123",
    "timestamp": 1709980800000
  }
}

Key Differences: No status wrapper, clearer field names, standardized metadata.

Deprecation Timeline

Planned Deprecations

Feature	Announced	Sunset Date	Replacement
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
API key only auth	Mar 2026	Mar 2027	OAuth 2.0 (keys still work)
Webhook v1 format	Q2 2026	Q2 2027	Webhook v2 format

Breaking Changes Detail

Removed Endpoints

/v1/stats — Replaced by /v2/metrics
/v1/historical — Replaced by /v2/historical with new parameters
/v1/alerts/create — Replaced by POST /v2/alerts

Parameter Changes

limit — Default changed from 100 to 20 (be explicit!)
timeframe — Now required on historical queries
sort — Format changed from "field asc" to "field:asc"

Response Field Changes

funding → funding_rate
price → mark_price
vol → volume_quote

Step-by-Step Migration

Phase 1: Planning (Week 1-2)

Audit existing integration for deprecated features
Map v1 endpoints to v2 equivalents
Identify breaking changes affecting your code
Plan testing strategy and timeline

Phase 2: Development (Week 3-4)

Create v2 branch in version control
Update all API endpoints to v2 URLs
Update request/response handling
Run unit tests against sandbox

Phase 3: Testing (Week 5-6)

Run full integration test suite
Test error scenarios and edge cases
Load testing with v2 endpoints
Security audit of updated code

Phase 4: Staging (Week 7)

Deploy v2 code to staging environment
Run full acceptance tests
Get sign-off from stakeholders
Prepare rollback plan

Phase 5: Production (Week 8)

Blue-green deploy to production
Monitor metrics and error rates
Stay on call for support issues
Gradually decommission v1 code

Support & Resources

Available Tools

Migration Validator — Check code for deprecated usage
API Upgrade Checker — Compare v1 and v2 compatibility
Migration Checklist — PDF with tasks and timeline
Code Examples — Before/after migration samples

Getting Help

Email: support@smartmoneyapi.com
Documentation: See changelog-versioning.html
Discord: Community support channel
Enterprise: Dedicated migration engineer

Start Your Migration Today

Upgrade to API v2 with comprehensive migration tools, documentation, and support. Built to support zero-downtime migration.

Explore V2

V1 supported through Jan 2028. Plan your migration today.