Burn Token
Burns the user's holding of one token in one wallet and pays it out in the token's payment currency. wallet_id is required: holdings are per wallet, and the named wallet both holds the position being burned and signs the on-chain call (paying its gas). It must be this user's wallet and sit on the token's chain. The call takes no quantity: the wallet's holding of the token is burned. On chain the burn carries a minimum payout: if the pool price changes and the payout would fall below that floor before the burn is mined, the chain reverts and the transaction ends in error instead of paying out less.
The burn is asynchronous. It records a user transaction (type = 8, burn) and answers 200 with an empty body: no transaction ID is returned. To follow it, list the user's transactions with Get User Transactions filtered by types=8 and wait for the newest one to reach status 3 (done, with a chain hash) or 4 (error).
Required permission: token:burn
Request
POST /v2/users/{user_id}/tokens/{token_id}/burn
Parameters
| Name | Type | In | Description |
|---|---|---|---|
user_id | string | path | Required. User ID |
token_id | string | path | Required. Token ID |
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer <access_token> |
Content-Type | Required. application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
wallet_id | string | Yes | Wallet (wallets._id) whose holding is burned and that signs the burn. Must belong to the user and sit on the token's chain |
Example
curl --request POST \
--url '{{baseUrl}}/v2/users/680c02896d91ca0145cfeb81/tokens/68ae06cfcccf4e8fc19362d1/burn' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"wallet_id": "6a89b68e0c46ca4c941271aa"
}'
Response
200 OK with an empty body.
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed (wallet_id) — see details |
| 400 | 10016 | token_id or wallet_id is not a valid 24-character hex id |
| 400 | 10001 | Token not found (domain 5) |
| 400 | 10015 | Domain 1: wallet does not belong to this user on this network — the wallet does not exist, is not this user's, or is on another chain |
| 500 | 10000 | Unexpected server-side failure |
A failure after the burn was accepted (for example a wallet without native balance for gas, or a payout below the floor) does not become an HTTP error: the transaction ends in status = 4 with the reason in its error field.
See Errors for the error format and common codes.