Skip to main content

🧵 Migrate on-chain identity from /actions to dedicated endpoints

This guide covers the deprecation of on-chain identity operations exposed through the POST /actions generic action endpoint (tagged Custom) in v1.8.1, and the migration to the dedicated /on-chain-identity endpoints available in both v1.8.1 and v2.0.0. Deprecation Date: 31/10/2026

Background​

In v1.8.1 the POST /actions endpoint acts as a generic action dispatcher. Among the supported action types are several on-chain identity operations:

  • tcCreateOnChainIdentity
  • tcRegisterOnChainIdentity
  • tcAddOnChainIndividualClaim
  • tcAddOnChainInstitutionalClaim
  • tcRevokeOnChainClaim
  • tcAddWalletKeyToIdentity
  • tcRemoveWalletKeyFromIdentity

These action types are deprecated within POST /actions. Dedicated endpoints for each operation are available in v1.8.1 at /on-chain-identity and are carried forward to v2.0.0 at /v2/on-chain-identity. Migrate to the dedicated endpoints before upgrading to v2.0.0, since the generic /actions endpoint is not included in v2.

Endpoint mapping​

Create identity​

- POST /actions
- Body: { "action": "tcCreateOnChainIdentity", ... }

# v1.8.1
+ POST /on-chain-identity

# v2.0.0
+ POST /v2/on-chain-identity

Request body schema: tcCreateOnChainIdentity (unchanged).

Response: returns the created identity object (CreatedOnchainIdentity).

Register identity​

- POST /actions
- Body: { "action": "tcRegisterOnChainIdentity", "identityAddress": "0x...", ... }

# v1.8.1
+ POST /on-chain-identity/{identityAddress}/register

# v2.0.0
+ POST /v2/on-chain-identity/{identityAddress}/register

The identityAddress moves from the request body to the path. Request body schema: tcRegisterOnChainIdentity.

Response: 202 Accepted with a TransactionId and a Location header pointing to the transaction status resource.

Add claim (KYC / KYB)​

- POST /actions
- Body: { "action": "tcAddOnChainIndividualClaim" | "tcAddOnChainInstitutionalClaim", ... }

# v1.8.1
+ POST /on-chain-identity/{identityAddress}/claims

# v2.0.0
+ POST /v2/on-chain-identity/{identityAddress}/claims

Request body: oneOf — tcAddOnChainIndividualClaim or tcAddOnChainInstitutionalClaim.

Response: returns the added claim object (ClaimAdded).

Get claims​

- (not available as a dedicated action through /actions)

# v1.8.1
+ GET /on-chain-identity/{identityAddress}/claims

# v2.0.0
+ GET /v2/on-chain-identity/{identityAddress}/claims

Response: returns the list of claims (Claims) for the given identity.

Remove claim​

- (not available as a dedicated action through /actions)

# v1.8.1
+ DELETE /on-chain-identity/{identityAddress}/claims/{claimType}

# v2.0.0
+ DELETE /v2/on-chain-identity/{identityAddress}/claims/{claimType}

The claimType (e.g. KYC) is a path parameter.

Response: returns the removed claim confirmation (ClaimRemoved).

Revoke claim permanently​

- POST /actions
- Body: { "action": "tcRevokeOnChainClaim", ... }

A permanent revoke (irreversible) was only available through POST /actions in v1.8.1. This action type is deprecated. If you need to revoke a claim, use the remove claim endpoint (DELETE /on-chain-identity/{identityAddress}/claims/{claimType}) which allows the claim to be re-added later.

Add / remove wallet key to identity​

- POST /actions
- Body: { "action": "tcAddWalletKeyToIdentity" | "tcRemoveWalletKeyFromIdentity", ... }

These action types are deprecated in POST /actions. Contact Token City support if your integration depends on wallet key management operations.

Why migrate now​

  • POST /actions will not be included in v2.0.0. Any integration that defers this migration will face a breaking change when upgrading to v2.
  • The dedicated endpoints provide cleaner semantics: individual HTTP verbs (POST, GET, DELETE) per operation, proper path parameters, and standard status codes (e.g. 202 Accepted with Location header for async operations).
  • The dedicated endpoint responses are stable and documented with explicit schemas. The POST /actions response uses a oneOf across all possible action results, making it harder to type-check or validate.

Migration steps​

  1. Identify all POST /actions calls in your codebase that use an on-chain identity action type (tcCreateOnChainIdentity, tcRegisterOnChainIdentity, tcAddOnChainIndividualClaim, tcAddOnChainInstitutionalClaim, tcRevokeOnChainClaim, tcAddWalletKeyToIdentity, tcRemoveWalletKeyFromIdentity).

  2. Replace each call with its corresponding dedicated endpoint from the table above.

  3. Move path-level identifiers (identityAddress, claimType) out of the request body and into the URL path as required by the new endpoints.

  4. Update response handling — the dedicated endpoints return focused schemas instead of a oneOf union. Narrow your types accordingly.

  5. Test in the development environment (https://dev-bsapi.token-city.com) before deploying.