Skip to main content

Cancel OTC Deal

Cancel an active OTC (Over-The-Counter) deal that was previously created.

Endpoint​

POST /v2/users/otcs/users/{user_id}/tokens/{token_id}/cancel

Headers​

HeaderValue
Content-Typeapplication/json
AuthorizationBearer {token}

Path Parameters​

ParameterTypeRequiredDescription
user_idstringYesThe unique identifier of the user who owns the deal
token_idstringYesThe unique identifier of the token

Request Body​

{
    "deal_id": 12
}

Parameters​

ParameterTypeRequiredDescription
deal_idnumberYesThe unique identifier of the deal to cancel

Response​

Returns confirmation of the deal cancellation.

Success Response (200 OK)​

{
    "success": true,
    "message": "OTC deal cancelled successfully",
    "data": {
        "deal_id": "number",
        "user_id": "string",
        "token_id": "string",
        "quantity": "number",
        "remaining_quantity": "number",
        "price": {
            "amount": "number",
            "decimal": "number",
            "symbol": "string"
        },
        "status": "string",
        "cancelled_at": "string",
        "created_at": "string",
        "cancellation_reason": "string"
    }
}

Example​

Request​

curl -X POST "\{\{baseUrl\}\}/v2/users/otcs/users/680c02896d91ca0145cfeb81/tokens/68ae06cfcccf4e8fc19362d1/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}" \
  -d '{
    "deal_id": 12
  }'

Response​

{
    "success": true,
    "message": "OTC deal cancelled successfully",
    "data": {
        "deal_id": 12,
        "user_id": "680c02896d91ca0145cfeb81",
        "token_id": "68ae06cfcccf4e8fc19362d1",
        "quantity": 50,
        "remaining_quantity": 35,
        "price": {
            "amount": 12.0,
            "decimal": 6,
            "symbol": "USDT"
        },
        "status": "cancelled",
        "cancelled_at": "2024-01-15T16:30:00Z",
        "created_at": "2024-01-15T10:30:00Z",
        "cancellation_reason": "User requested cancellation"
    }
}

Error Responses​

400 Bad Request​

{
    "error": "Invalid parameters",
    "details": "Deal ID is required"
}

401 Unauthorized​

{
    "error": "Authentication required"
}

403 Forbidden​

{
    "error": "Access denied",
    "details": "You can only cancel your own deals"
}

404 Not Found​

{
    "error": "Deal not found",
    "details": "The specified deal does not exist"
}

409 Conflict​

{
    "error": "Deal cannot be cancelled",
    "details": "Deal is already completed or expired"
}

500 Internal Server Error​

{
    "error": "Internal server error"
}

Important Notes​

  • Ownership Verification: Only the creator of the deal can cancel it
  • Deal Status: Only active deals can be cancelled
  • Token Return: Any locked tokens are returned to the user's available balance
  • Partial Execution: If the deal was partially executed, only the remaining quantity is cancelled
  • Counterparty Notification: Any interested counterparties are notified of the cancellation
  • Irreversible Action: Once cancelled, the deal cannot be reactivated
  • No Penalties: There are typically no penalties for cancelling OTC deals
  • Audit Trail: All cancellations are logged for audit and compliance purposes