Polkadot: Migration guide to the v1 REST API

The underlying Polkadot network infrastructure is transitioning from the legacy Node.js substrate-api-sidecar to the new Rust-based Polkadot REST API. This change follows the upstream deprecation of substrate-api-sidecar by Parity and its replacement with polkadot-rest-api.

🚧

Attention

Tatum has deployed support for the new /v1 REST API paths for Polkadot, Kusama, Westend, and Asset Hub networks. The legacy /substrateapi paths remain available in parallel for the time being to give customers time to migrate. However, because substrate-api-sidecar is deprecated upstream, we recommend updating your integrations to the new /v1 paths as soon as possible.

For complete technical details, see the Official Parity Migration Guide.

What is changing?

Polkadot-based REST API endpoints are moving from the legacy /substrateapi path to the new /v1 path.

For example, the current endpoint:

GET https://polkadot-mainnet.gateway.tatum.io/substrateapi/accounts/15XQrm3X1UtiBF1qBpwb5y9kMMyfK7PxgWhotAJPqv2r6YCD/asset-balances

should be updated to:

GET https://polkadot-mainnet.gateway.tatum.io/v1/accounts/15XQrm3X1UtiBF1qBpwb5y9kMMyfK7PxgWhotAJPqv2r6YCD/asset-balances

In most cases, the migration requires replacing:

/substrateapi

with:

/v1

Affected networks

This migration applies to Polkadot-based REST API endpoints, including:

• Polkadot Mainnet
• Polkadot Asset Hub
• Polkadot Westend
• Kusama Mainnet
• Kusama Asset Hub

Required actions

If your application uses Polkadot, Kusama, Westend, or Asset Hub REST API endpoints through Tatum Gateway, please update your integration.

1. Identify all API calls using /substrateapi.
2. Replace /substrateapi with /v1.
3. Test the updated endpoints in your application.
4. Review response parsing logic for compatibility with the new API.
5. Update Postman collections, SDK wrappers, monitoring, and internal documentation where applicable.

🚧

Backward compatibility

Tatum plans to run both the legacy /substrateapi endpoints and the new /v1 endpoints in parallel for the time being.

However, since the underlying substrate-api-sidecar project is deprecated upstream, the legacy implementation should not be treated as long-term stable infrastructure. We strongly recommend migrating to the new /v1 endpoints as soon as possible.