This endpoint verifies whether a given transfer is eligible to be clawed back. It performs non-mutating checks only and DOES NOT initiate a clawback. The goal is to prevent double-spend and ensure only genuine stuck funds are considered for clawback.

Eligibility Requirements

To be eligible for clawback, a transfer must:

• Exist and be a valid Spark transfer
• Be sent from the authenticated user (verified against Sparkscan data)
• Not be already reserved or used in the system (Redis check)
• Not have been claimed/settled (Sparkscan status check)
• Be less than 241 hours old (10 days + 1 hour buffer)
• Have valid proof on the Spark network

Process Flow

1. Validates the request and authentication
2. Checks that the transfer is not currently reserved/spent (Redis - fast path)
3. Verifies the transfer exists and has valid status with Sparkscan

• For Bitcoin transfers: CONFIRMED status means the transfer was claimed and cannot be clawed back
• This is the authoritative check for transfer eligibility

4. Verifies the authenticated user is the sender of the transfer
5. Ensures the transfer age is within the allowed window

Important Notes

• This is a read-only eligibility check; it does NOT initiate a clawback
• Only the original sender of the transfer can check eligibility (verified via Sparkscan)
• Clawbacks are only for genuine stuck funds, not for reversing completed transactions
• The 241-hour (10 day) limit prevents long-term replay attacks while giving adequate recovery time
• The settlement service will perform full verification again before processing any clawback

Arguments

Body:

• spark_transfer_id - Transfer ID to evaluate for clawback

Auth:

• Bearer token in Authorization header - the public key from the token is verified against the transfer sender in Sparkscan to ensure only the original sender can check eligibility

Returns

• 200 OK with CheckClawbackEligibilityResponse:

• accepted: true if the transfer is eligible for clawback
• accepted: false with error message if ineligible (reserved, claimed, too old, not found, etc.)

• 400 Bad Request if request payload validation fails
• 401 Unauthorized if authentication fails or token is invalid