Buy On Secondary Market
Buys an open secondary-market listing (deal_id) from another user. A listing is bought whole: the contract takes only the deal ID and transfers the entire listing, so quantity must equal the listing's quantity (see List Token Listings); any other value is refused with 11004. The price is the listing's, and the buyer pays the buy-order fee on top; show the cost first with Quote Secondary Market Purchase.
The buy is asynchronous: it records a pending purchase and a user transaction (type = 2, purchase on secondary market) and answers with its transaction_id. Poll Get User Transaction until status is 3 (done) or 4 (error).
wallet_id is required and names the buyer's wallet the tokens are bought into. It must be this user's wallet and sit on the token's chain; it is never derived. That wallet signs the purchase and pays the gas, so fund the wallet you name. The seller's side comes from the listing, which names the wallet it is sold from; a listing that names no wallet cannot be bought.
Required permission: purchase:create
Request
POST /v2/users/{user_id}/purchases/tokens/{token_id}/buy-on-secondary-market
Parameters
| Name | Type | In | Description |
|---|---|---|---|
user_id | string | path | Required. Buyer's 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 |
|---|---|---|---|
deal_id | integer | Yes | Listing (deal) to buy |
quantity | integer | Yes | Must equal the listing's quantity |
wallet_id | string | Yes | Buyer's wallet (wallets._id) the tokens are bought into and the purchase is signed from. Must belong to the user and sit on the token's chain |
Example
curl --request POST \
--url '{{baseUrl}}/v2/users/680c02896d91ca0145cfeb81/purchases/tokens/68ae06cfcccf4e8fc19362d1/buy-on-secondary-market' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"deal_id": 13,
"quantity": 10,
"wallet_id": "6a89b68e0c46ca4c941271aa"
}'
Response
{
"transaction_id": "6913872755654191dede37da"
}
Response Fields
| Field | Type | Description |
|---|---|---|
transaction_id | string | User transaction that carries the purchase. Poll it with Get User Transaction |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed (deal_id, quantity, wallet_id) — see details |
| 400 | 10016 | user_id, token_id or wallet_id is not a valid 24-character hex id |
| 400 | 11001 | Domain 11: no listing with this deal_id on this token, or the listing names no wallet and cannot be bought |
| 400 | 11002 | The listing is not open (domain 11, secondary market is not active) |
| 400 | 11004 | quantity does not equal the listing's quantity (domain 11) |
| 400 | 10001 | Token not found (domain 5) |
| 400 | 10011 | Token is not listed (domain 5, token is not active) |
| 400 | 10012 | Token is not open to the secondary market (domain 5) |
| 400 | 10001 | Buyer or seller user not found (domain 1) |
| 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 buy was accepted 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.