Claim Rent
Claims one rent payout of the user into one of the user's wallets. rent_id is the payout's external_id from List Rents By Token (an integer, not an ObjectID). wallet_id is required: that wallet signs the claim, pays its gas and receives the payout. It must be this user's wallet and sit on the token's chain.
The claim is asynchronous. It records a user transaction (type = 5, claim rent) 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=5 and wait for the newest one to reach status 3 (done) or 4 (error). The currency lands in the wallet only after 3.
A payout that is already being claimed, or was already claimed, is refused with 409 before any transaction is created, so a retry or a double submit cannot claim twice.
Required permission: rent:claim
Request
POST /v2/users/{user_id}/rents/tokens/{token_id}/{rent_id}/claim
Parameters
| Name | Type | In | Description |
|---|---|---|---|
user_id | string | path | Required. User ID |
token_id | string | path | Required. Token ID |
rent_id | integer | path | Required. The payout's external_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) that signs the claim and receives the payout. Must belong to the user and sit on the token's chain |
Example
curl --request POST \
--url '{{baseUrl}}/v2/users/680c02896d91ca0145cfeb81/rents/tokens/68ae06cfcccf4e8fc19362d1/1/claim' \
--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, or rent_id not a positive integer) — see details |
| 400 | 10016 | user_id, token_id or wallet_id is not a valid 24-character hex id |
| 400 | 10001 | Domain 5: token not found (token not found) or no payout with this rent_id for the user on this token (rent not found) |
| 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 |
| 409 | 10002 | The payout is already being claimed or was already claimed (domain 5) |
| 500 | 10000 | Unexpected server-side failure |
See Errors for the error format and common codes.