This endpoint allows users to recover funds that were sent to an LP wallet but were not properly processed. This is a safety mechanism to prevent permanent loss of funds.

Eligibility Requirements

To be eligible for clawback, a transfer must:

• Be sent from the authenticated user to a valid LP wallet
• Not be already reserved or used in the system
• Be less than 23 hours old (to prevent abuse)
• Have valid proof on the Spark network

Process Flow

1. Validates the request and authentication
2. Checks that the transfer is not already reserved
3. Verifies the transfer details with Sparkscan
4. Ensures the transfer age is within the allowed window
5. Sends the clawback request to the settlement service
6. Returns tracking information for the refund

Important Notes

• Clawbacks are only for genuine stuck funds, not for reversing completed transactions
• The 23-hour limit prevents long-term replay attacks
• Only the original sender can request a clawback
• The settlement service will verify the request again before processing

Authentication

Requires a valid JWT bearer token. The token’s public key must match the sender_public_key in the request.

Arguments

• sender_public_key - Public key of the original sender
• spark_transfer_id - Transfer ID to claw back
• lp_identity_public_key - LP wallet that received the funds
• nonce - Unique value for replay protection
• signature - Request signature

Returns

• 200 OK with tracking information if clawback is accepted
• 400 Bad Request if validation fails or transfer is ineligible
• 401 Unauthorized if authentication fails
• 409 Conflict if nonce already used
• 500 Internal Server Error if clawback processing fails