Buy On Secondary Market

Purchase tokens from other users on the secondary market at market-determined prices.

Endpoint

POST /v2/users/purchases/users/{user_id}/tokens/{token_id}/buy-on-secondary-market

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
user_id	string	Yes	The unique identifier of the user making the purchase
token_id	string	Yes	The unique identifier of the token to purchase

Request Body

{
    "quantity": 10,
    "deal_id": 13
}

Parameters

Parameter	Type	Required	Description
quantity	number	Yes	Number of tokens to purchase
deal_id	number	Yes	The unique identifier of the specific deal/listing to purchase from

Response

Returns confirmation of the secondary market purchase.

Success Response (200 OK)

{
    "success": true,
    "message": "Secondary market purchase successful",
    "data": {
        "purchase_id": "string",
        "user_id": "string",
        "token_id": "string",
        "deal_id": "number",
        "quantity": "number",
        "unit_price": {
            "amount": "number",
            "decimal": "number",
            "symbol": "string"
        },
        "total_cost": {
            "amount": "number",
            "decimal": "number",
            "symbol": "string"
        },
        "fees": {
            "platform_fee": {
                "amount": "number",
                "decimal": "number",
                "symbol": "string"
            },
            "node_fee": {
                "amount": "number",
                "decimal": "number",
                "symbol": "string"
            }
        },
        "net_amount": {
            "amount": "number",
            "decimal": "number",
            "symbol": "string"
        },
        "seller_id": "string",
        "seller_name": "string",
        "status": "string",
        "transaction_hash": "string",
        "purchase_date": "string",
        "estimated_delivery": "string"
    }
}

Example

Request

curl -X POST "\{\{baseUrl\}\}/v2/users/purchases/users/680c02896d91ca0145cfeb81/tokens/68ae06cfcccf4e8fc19362d1/buy-on-secondary-market" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}" \
  -d '{
    "quantity": 10,
    "deal_id": 13
  }'

Response

{
    "success": true,
    "message": "Secondary market purchase successful",
    "data": {
        "purchase_id": "sm_purchase_456",
        "user_id": "680c02896d91ca0145cfeb81",
        "token_id": "68ae06cfcccf4e8fc19362d1",
        "deal_id": 13,
        "quantity": 10,
        "unit_price": {
            "amount": 12.5,
            "decimal": 6,
            "symbol": "USDT"
        },
        "total_cost": {
            "amount": 125.0,
            "decimal": 6,
            "symbol": "USDT"
        },
        "fees": {
            "platform_fee": {
                "amount": 3.75,
                "decimal": 6,
                "symbol": "USDT"
            },
            "node_fee": {
                "amount": 2.5,
                "decimal": 6,
                "symbol": "USDT"
            }
        },
        "net_amount": {
            "amount": 131.25,
            "decimal": 6,
            "symbol": "USDT"
        },
        "seller_id": "680c02896d91ca0145cfeb82",
        "seller_name": "John Doe",
        "status": "completed",
        "transaction_hash": "0x1234567890abcdef1234567890abcdef12345678",
        "purchase_date": "2024-01-15T16:30:00Z",
        "estimated_delivery": "2024-01-15T16:35:00Z"
    }
}

Error Responses

400 Bad Request

{
    "error": "Invalid parameters",
    "details": "Quantity and deal_id are required"
}

401 Unauthorized

{
    "error": "Authentication required"
}

403 Forbidden

{
    "error": "Access denied",
    "details": "Insufficient permissions to purchase tokens"
}

404 Not Found

{
    "error": "Deal not found",
    "details": "The specified deal is no longer available"
}

409 Conflict

{
    "error": "Deal conflict",
    "details": "Another user has already purchased this quantity"
}

422 Unprocessable Entity

{
    "error": "Purchase not possible",
    "details": "Insufficient quantity available in the deal"
}

500 Internal Server Error

{
    "error": "Internal server error"
}

Important Notes

• Market Prices: Prices are set by individual sellers and may vary
• Deal Availability: Deals can be partially filled or expire
• Quantity Limits: Cannot purchase more than the available quantity in a deal
• Seller Verification: All sellers are verified users on the platform
• Atomic Transactions: Purchases are processed atomically to prevent double-spending
• Fee Structure: Includes platform and node fees based on transaction value
• Settlement Time: Tokens are typically delivered within minutes
• Price Discovery: Secondary market enables price discovery through supply and demand