Pause and unpause assets
Enable or disable all transfers for an asset via API.
Pausing an asset disables all transfers, minting, and burning immediately. Operators use this for emergency stops, maintenance windows, and compliance holds. These operations change the transfer state for one token while preserving the rest of the platform state.
To pause or unpause through the web interface instead, see the user guide. The API approach gives you programmatic control and is suitable for automated workflows.
Prerequisites
- Platform URL (e.g.,
https://your-platform.example.com) - API key scoped to a user with the Emergency role on this asset. See Getting Started for setup.
- Wallet verification enabled on your account (pincode or 2FA)
Pausing an asset
The Platform API requires wallet verification for every pause operation, so the caller must supply a valid pincode or TOTP code. The platform validates the Emergency role before sending the on-chain transaction.
Prepare the pause request
Send a PATCH to the pause-state endpoint with your wallet verification credentials. Include the token contract address in the URL path.
curl -X PATCH "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/pause-state" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"walletVerification": {
"secretVerificationCode": "123456",
"verificationType": "PINCODE"
}
}'Execute pause
When you execute the request, the platform validates your Emergency role, verifies your wallet credentials, and sets the pause flag on-chain. All three steps must succeed before the transaction submits.
- Validates your permissions - Confirms you have Emergency role on this asset
- Verifies your wallet - Uses your pincode/2FA to authorize the blockchain transaction
- Pauses the asset - Sets the pause flag on-chain, blocking all transfers
Handle response
A synchronous response wraps the updated token data in data and includes transaction metadata. Check data.pausable.paused to confirm the operation succeeded.
{
"data": {
"id": "0x9459D52E60edBD3178f00F9055f6C117a21b4220",
"name": "ACME Holdings Common Stock",
"symbol": "ACME",
"decimals": 0,
"totalSupply": "1000",
"type": "equity",
"pausable": {
"paused": true
}
},
"meta": {
"txHashes": ["0x..."]
},
"links": {
"self": "/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/pause-state"
}
}The data.pausable.paused field confirms the token is now paused. The full object also carries accessControl, identity, and userPermissions. For asynchronous processing, the API returns a transactionId, status, and statusUrl instead.
Unpausing an asset
The unpause flow mirrors the pause flow: supply your wallet verification credentials and the platform clears the on-chain flag, re-enabling transfers immediately.
Prepare the unpause request
Send a DELETE to the pause-state endpoint with your wallet verification credentials. Include the token contract address in the URL path.
curl -X DELETE "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/pause-state" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"walletVerification": {
"secretVerificationCode": "123456",
"verificationType": "PINCODE"
}
}'Execute unpause
When you execute the request, the platform validates your Emergency role, verifies your wallet credentials, and clears the on-chain pause flag. All three steps must succeed before transfers re-enable.
- Validates your permissions - Confirms you have Emergency role on this asset
- Verifies your wallet - Uses your pincode/2FA to authorize the blockchain transaction
- Unpauses the asset - Clears the pause flag, enabling all transfers
Handle response
A synchronous response wraps the updated token data in data and includes transaction metadata. Check data.pausable.paused to confirm the operation succeeded.
{
"data": {
"id": "0x9459D52E60edBD3178f00F9055f6C117a21b4220",
"name": "ACME Holdings Common Stock",
"symbol": "ACME",
"decimals": 0,
"totalSupply": "1000",
"type": "equity",
"pausable": {
"paused": false
}
},
"meta": {
"txHashes": ["0x..."]
},
"links": {
"self": "/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/pause-state"
}
}The data.pausable.paused field confirms the token is now active. The full object also carries accessControl, identity, and userPermissions. For asynchronous processing, the API returns a transactionId, status, and statusUrl instead.
Request parameters
Both pause and unpause accept the same body shape.
| Parameter | Type | Required | Description |
|---|---|---|---|
walletVerification | object | Yes | Your wallet verification |
walletVerification.secretVerificationCode | string | Yes | Your 6-digit PINCODE or TOTP code |
walletVerification.verificationType | string | Yes | "PINCODE", "OTP", or "SECRET_CODES" |
What pausing affects
When the platform pauses a token, it blocks wallet-to-wallet transfers, minting, burning, and forced administrative transfers.
The following continue to work while paused: balance reads, identity verification, claim checks, role management, and the ability to toggle the paused state.
Check pause status
Query the token to read its current pause state. The response wraps the result in the data.pausable field. The following example shows the request and a sample response:
curl -X GET "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220" \
-H "X-Api-Key: YOUR_API_KEY"{
"data": {
"id": "0x9459D52E60edBD3178f00F9055f6C117a21b4220",
"name": "ACME Holdings Common Stock",
"symbol": "ACME",
"decimals": 0,
"totalSupply": "1000",
"type": "equity",
"pausable": {
"paused": false
}
},
"links": {
"self": "/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220"
}
}Use data.pausable.paused to confirm the current pause state.
Troubleshooting
| Issue | Solution |
|---|---|
401 Unauthorized | API key is invalid, expired, or disabled |
403 USER_NOT_AUTHORIZED | Ensure your account has emergency role on this asset |
Asset already paused | Read the current status; the platform already paused this asset |
Asset already unpaused | Read the current status; the platform already unpaused this asset |
Cannot transfer while paused | Unpause the asset before attempting transfers |
Related guides
- Forced Transfer: administrative transfers
- Mint Assets: issue assets to investors