# Pause and unpause assets
Source: https://docs.settlemint.com/docs/developers/asset-servicing/pause-unpause-asset
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](/docs/operators/asset-servicing/pause-unpause-asset). The API approach gives you programmatic control and is suitable for automated workflows.
## Prerequisites [#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](/docs/api-reference/reference/getting-started) for setup.
* Wallet verification enabled on your account (pincode or 2FA)
The platform pauses every asset on creation. You must unpause before any transfers can occur.
## Pausing an asset [#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 [#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.
```bash
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"
}
}'
```
The asset contract address is part of the URL path: `/api/v2/tokens/{tokenAddress}/pause-state`.
### Execute pause [#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.
1. **Validates your permissions** - Confirms you have Emergency role on this asset
2. **Verifies your wallet** - Uses your pincode/2FA to authorize the blockchain transaction
3. **Pauses the asset** - Sets the pause flag on-chain, blocking all transfers
### Handle response [#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.
```json
{
"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 [#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 [#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.
```bash
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 [#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.
1. **Validates your permissions** - Confirms you have Emergency role on this asset
2. **Verifies your wallet** - Uses your pincode/2FA to authorize the blockchain transaction
3. **Unpauses the asset** - Clears the pause flag, enabling all transfers
### Handle response [#handle-response-1]
A synchronous response wraps the updated token data in `data` and includes transaction metadata. Check `data.pausable.paused` to confirm the operation succeeded.
```json
{
"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 [#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 [#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.
Pausing affects all holders immediately. Use sparingly and notify affected parties before pausing.
## Check pause status [#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:
```bash
curl -X GET "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220" \
-H "X-Api-Key: YOUR_API_KEY"
```
```json
{
"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 [#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 [#related-guides]
* [Forced Transfer](/docs/developers/asset-servicing/forced-transfer): administrative transfers
* [Mint Assets](/docs/developers/asset-servicing/mint-assets): issue assets to investors