Migration Guide

Migrate from direct API calls to the Paxos SDK for automatic authentication, retries, pagination, and typed errors.

If you already integrate with Paxos APIs using raw HTTP calls, you can migrate to the SDK incrementally. The SDK handles authentication, retries, pagination, and error parsing automatically — eliminating boilerplate you currently maintain.

Why Migrate?

Concern	Direct API Calls	With the SDK
Authentication	Manual token management, refresh logic, thread safety	Automatic — handled by the SDK
Retries	Manual retry loops with backoff and jitter	Automatic — 429 and 5xx retried with exponential backoff
Pagination	Manual cursor tracking and page fetching	Automatic — iterators handle page boundaries
Error handling	Parse JSON, check status codes, extract request ID	Typed errors with IsNotFound(), IsRateLimited(), etc.
Idempotency	Generate and manage idempotency keys manually	Automatic — SDK generates keys for retried mutating requests

Before and After

Authentication

Before — Manual token acquisition and injection:

# Get a token
TOKEN=$(curl -s -X POST https://oauth.sandbox.paxos.com/oauth2/token \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$PAXOS_CLIENT_ID" \
  --data-urlencode "client_secret=$PAXOS_CLIENT_SECRET" \
  | jq -r '.access_token')

# Use the token
curl https://api.sandbox.paxos.com/v2/transfer/transfers/txn_123 \
  -H "Authorization: Bearer $TOKEN"

After — The SDK handles it:

Go

client, _ := paxos.NewClient(os.Getenv("PAXOS_CLIENT_ID"), os.Getenv("PAXOS_CLIENT_SECRET"), paxos.WithSandbox())
transfer, err := client.Transfers.GetTransfer(ctx, "txn_123")

Pagination

Before — Manual cursor loop:

var cursor string
for {
    resp, _ := http.Get(fmt.Sprintf("https://api.sandbox.paxos.com/v2/transfer/transfers?limit=50&page_cursor=%s", cursor))
    var result ListResponse
    json.NewDecoder(resp.Body).Decode(&result)

    for _, t := range result.Items {
        process(t)
    }

    if result.NextPageCursor == "" {
        break
    }
    cursor = result.NextPageCursor
}

After — Auto-pagination iterator:

for iter := client.Transfers.ListTransfers(ctx, &paxos.ListTransfersRequest{Limit: 50}); iter.Next(); {
    process(iter.Current())
}

Error Handling

Before — Raw status code checks:

resp, _ := http.Get(url)
if resp.StatusCode == 429 {
    time.Sleep(time.Second * 5)
    // retry...
} else if resp.StatusCode == 404 {
    // not found...
}

After — Typed error checking:

transfer, err := client.Transfers.GetTransfer(ctx, "txn_123")
if paxos.IsNotFound(err) {
    // handle not found
}
// 429 and 5xx are retried automatically

Migration Checklist

Use this checklist to migrate incrementally:

• Install the SDK (Go, Python, TypeScript, Java)
• Replace token management code with SDK client construction
• Replace HTTP call sites with SDK service methods one at a time
• Replace manual error handling with typed SDK errors
• Replace pagination loops with SDK iterators
• Test each migrated call against Sandbox
• Deploy to production

Incremental Migration

You don’t have to migrate everything at once. The SDK client can coexist with your existing HTTP code. Start with the endpoints you call most frequently, then migrate the rest over time.

The SDK uses the same underlying REST API — there are no behavioral differences between SDK calls and direct API calls.