v2 → v3 Migration Guide

Breaking

Step-by-step guide for migrating from DUAL API v2 to v3. Covers authentication, endpoint renames, pagination, and error handling changes with before/after code examples.

Deprecation Timeline

v2 endpoints return 301 redirects to their v3 equivalents. This compatibility layer will be removed in June 2026. Migrate before then to avoid breaking changes.

Changes at a Glance

Area	v2	v3
Base URL	`https://api.dual.io`	`https://blockv-labs.io`
Authentication	`App-Id + App-Secret headers`	`Bearer JWT token`
Error Format	`{message: string}`	`{code: string, status: number, body: object}`
Pagination	`Offset-based (offset/limit)`	`Cursor-based (cursor)`
User Endpoints	`/user/*`	`/wallets/*`
Digital Assets	`/vatoms/*`	`/objects/*`
Asset Actions	`/vatoms/:id/actions`	`/ebus/actions`

1. Authentication

v2 used static App-Id and App-Secret headers. v3 uses JWT bearer tokens obtained through the login endpoint, with automatic refresh support.

v2 — App-Id / App-Secret

curl https://api.dual.io/user/profile \
  -H "App-Id: YOUR_APP_ID" \
  -H "App-Secret: YOUR_APP_SECRET"

v3 — Bearer JWT

# Login to get a token
curl -X POST https://blockv-labs.io/wallets/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# Use the token in subsequent requests
curl https://blockv-labs.io/wallets/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1..."

2. Error Handling

v3 errors include a machine-readable error code, HTTP status, and a detailed body with context about the failure.

v2 Error

// v2 error response
{
  "message": "Not found"
}

v3 Error

// v3 error response
{
  "code": "RESOURCE_NOT_FOUND",
  "status": 404,
  "body": {
    "message": "Object obj_123 not found",
    "resource": "object",
    "id": "obj_123"
  }
}

3. Pagination

v3 uses cursor-based pagination for consistent results. Offset pagination is deprecated and will be removed in v4.

v2 Offset

// v2: Offset pagination
GET /vatoms?offset=20&limit=10

// Response
{
  "items": [...],
  "total": 150,
  "offset": 20,
  "limit": 10
}

v3 Cursor

// v3: Cursor pagination
GET /objects?limit=10&cursor=eyJpZCI6Im9ial8xMjMifQ

// Response
{
  "items": [...],
  "cursor": "eyJpZCI6Im9ial8xMzMifQ",
  "has_more": true
}

4. Endpoint Renames

v2 Endpoint	→	v3 Endpoint
`GET /user/profile`	→	`GET /wallets/me`
`POST /user/login`	→	`POST /wallets/login`
`POST /user/register`	→	`POST /wallets/register`
`GET /vatoms`	→	`GET /objects`
`GET /vatoms/:id`	→	`GET /objects/:id`
`POST /vatoms/:id/actions`	→	`POST /ebus/actions`
`GET /templates`	→	`GET /templates`
`POST /user/token/refresh`	→	`POST /wallets/token/refresh`
`GET /activity`	→	`GET /ebus/events`
`POST /vatoms/:id/transfer`	→	`POST /objects/:id/transfer`

5. Automated Codemod

Run this bash script from your project root to automatically rename endpoints and update headers. Always review the diff before committing.

migrate-v2-to-v3.sh

#!/bin/bash
# Run from your project root
find src -name "*.ts" -o -name "*.js" | xargs sed -i '' \
  -e 's|api.dual.io|blockv-labs.io|g' \
  -e 's|/user/profile|/wallets/me|g' \
  -e 's|/user/login|/wallets/login|g' \
  -e 's|/user/register|/wallets/register|g' \
  -e 's|/vatoms|/objects|g' \
  -e 's|App-Id|Authorization|g' \
  -e 's|/activity|/ebus/events|g' \
  -e 's|/user/token/refresh|/wallets/token/refresh|g'
echo "Migration complete — review changes with: git diff"

Need help migrating? Open a support ticket or ask in the Discord.