Talaan ng mga Nilalaman

Pangkalahatang-ideya Patakaran sa Bersyon Pagkatugma sa Nakaraan Paglipat mula V1 patungong V2 Mga Pagbabago sa Endpoint Mga Update sa Format ng Tugon Timeline ng Pagtanggal Mga Pagbabagong Nakakaapekto Step-by-Step na Paglipat Suporta at Mga Mapagkukunan

Dokumentasyon ng API

API Migration Guide — Pag-upgrade sa Pagitan ng mga Bersyon

Planuhin at isagawa ang maayos na pag-upgrade ng bersyon ng API. Unawain ang mga pagbabagong nakakaapekto, timeline ng pagtanggal, at mga pinakamahusay na pamamaraan para sa paglipat sa pagitan ng mga bersyon ng Smart Money API.

Na-publish noong Marso 21, 2026 • 16 minutong pagbabasa • Advanced

Pangkalahatang-ideya ng Paglipat

Ang Smart Money API ay aktibong pinapaunlad na may regular na mga update. Saklaw ng gabay na ito ang pamamahala ng bersyon, mga pagbabagong nakakaapekto, at kung paano ilipat ang iyong integrasyon nang walang downtime.

Mga pangunahing prinsipyo ng paglipat:

Semantic Versioning — Mahigpit na sinusunod ang format na MAJOR.MINOR.PATCH
Long-Term Support — Ang nakaraang major na bersyon ay sinusuportahan ng 24+ buwan
Mga Babala sa Pagtanggal — 6 na buwang paunang abiso sa lahat ng pagbabagong nakakaapekto
Parallel Versions — Patakbuhin ang v1 at v2 nang sabay sa panahon ng paglipat
Automated Testing — Mga kasangkapan sa pagsubok ng compatibility na ibinigay

Kasalukuyang Katayuan: v1 (kasalukuyan), v2 (beta, pangkalahatang kagamitan Q2 2026). v1 sinusuportahan hanggang Q1 2028.

Patakaran sa Bersyon

Semantic Versioning

Format ng Bersyon
Bersyon ng API: MAJOR.MINOR.PATCH
Halimbawa: 2.1.3
MAJOR (2) - Mga pagbabagong nakakaapekto, bagong arkitektura
MINOR (1) - Mga feature na katugma sa nakaraan
PATCH (3) - Mga pag-aayos ng bug, update sa seguridad

Siklo ng Paglabas ng Bersyon

Yugto	Tagal	Mga Katangian
Alpha	2-4 na linggo	Malalaking pagbabagong nakakaapekto, pagsubok lamang
Beta	4-8 na linggo	Halos stable, feedback ng komunidad
Release Candidate	2-4 na linggo	Handa na sa produksyon, huling pino
Pangkalahatang Kagamitan	24+ buwan	Buong suporta sa produksyon

Kunin ang iyong API key sa loob ng 30 segundo

Handa nang magtayo? Kumuha ng libreng API key (100 tawag/araw, walang card) at simulan ang pagkuha ng live na data ng whale, funding, at on-chain.

Kunin ang iyong API key →

Pagkatugma sa Nakaraan

Pagkatugma ng Bersyon

Sa loob ng isang major na bersyon, maaari mong palaging i-upgrade sa mas bagong minor/patch na bersyon nang ligtas:

Mga URL ng Endpoint — Nananatiling hindi nagbabago
Mga Kinakailangang Field — Hindi kailanman tinanggal (mga bagong optional na field lamang ang idinagdag)
Mga HTTP Status Code — Pinapanatili para sa mga umiiral na senaryo
Istaktura ng Tugon — Ang mga pangunahing field ay nananatiling pareho
Pagpapatunay — Walang pagbabago sa mga mekanismo ng auth

Graceful Deprecation

Timeline ng Pagtanggal
// Buwan 1: I-anunsyo ang pagtanggal
// Ang feature ay minarkahan ng Deprecation header
Deprecation: version="2.2", sunset="2026-09-01"
// Buwan 3-6: Aktibong panahon ng pagtanggal
// Nagbabalik ng mga babala ang API ngunit gumagana pa rin
X-Deprecation-Warning: Ang endpoint na ito ay tatanggalin sa 2026-09-01
// Buwan 6: Panghuling pag-alis
// Ang endpoint ay nagbabalik ng 410 Gone
HTTP/1.1 410 Gone

Paglipat mula V1 patungong V2

Mga Pangunahing Pagbabago

Redisensyo ng REST API — Mas malinis na mga endpoint ng resource
Format ng Tugon — Pare-parehong pag-wrap, mas mahusay na paghawak ng error
Pagpapatunay — Idinagdag ang suporta sa OAuth 2.0 (gumagana pa rin ang mga API key)
Rate Limiting — Pinahusay na granularity at kalinawan
Webhooks — Redisensyadong format ng event at pag-sign

Endpoint Mapping

v1 Endpoint	v2 Endpoint	Mga Pagbabago
GET /whales	GET /v2/whales/tracking	Inayos muli, idinagdag ang filtering
GET /funding	GET /v2/derivatives/funding-heatmap	Kinakailangan ang parameter ng exchange
GET /positions	GET /v2/derivatives/positions	Mga bagong opsyon sa aggregation

Mga Pagbabago sa Endpoint

Mga Pagbabago sa Parameter ng Kahilingan

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

V2 Request
// V2: Parehong data, mas malinaw na istraktura
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Mga Update sa Format ng Tugon

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: Walang status wrapper, mas malinaw na pangalan ng field, 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: [email protected]
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.