Clawback Funds

curl --request POST \
  --url https://api.amm.flashnet.xyz/v1/clawback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "lpIdentityPublicKey": "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
  "nonce": "clawback-nonce-123456",
  "senderPublicKey": "02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567",
  "signature": "3045022100a7e5d4f8b2c9a1e6f0d5b8c4a9e7f2d1c8b5a4e9f0d6c5b3a2e1d0c9b8a7f02201f2e3d4c5b6a7980e9f0a1b2c3d4e5f67889a0b1c2d3e4f5a6b7c8d9e0f1a2b3",
  "sparkTransferId": "550e8400-e29b-41d4-a716-446655440000"
}
'

{
  "accepted": true,
  "internalRequestId": "settlement-internal-123",
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW",
  "sparkStatusTrackingId": "spark-track-456"
}

Clawback

Clawback Funds

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 10 days old (to prevent abuse)
Have valid proof on the Spark network
Not be already used in amm_swaps or amm_liquidity tables

Process Flow

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

Important Notes

Clawbacks are only for genuine stuck funds, not for reversing completed transactions
The 10-day 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

POST

clawback

Clawback Funds

curl --request POST \
  --url https://api.amm.flashnet.xyz/v1/clawback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "lpIdentityPublicKey": "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
  "nonce": "clawback-nonce-123456",
  "senderPublicKey": "02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567",
  "signature": "3045022100a7e5d4f8b2c9a1e6f0d5b8c4a9e7f2d1c8b5a4e9f0d6c5b3a2e1d0c9b8a7f02201f2e3d4c5b6a7980e9f0a1b2c3d4e5f67889a0b1c2d3e4f5a6b7c8d9e0f1a2b3",
  "sparkTransferId": "550e8400-e29b-41d4-a716-446655440000"
}
'

{
  "accepted": true,
  "internalRequestId": "settlement-internal-123",
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW",
  "sparkStatusTrackingId": "spark-track-456"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Clawback request details including transfer ID and authentication

Request body for clawing back stuck funds.

Clawbacks allow users to recover funds that were sent to an LP wallet but were not processed correctly. This is a safety mechanism to prevent permanent loss of funds due to system failures or edge cases.

senderPublicKey

string

required

Public key of the original sender requesting the clawback. Must match the authenticated user's public key.

Example:

"02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567"

sparkTransferId

string

required

Spark transfer ID or transaction ID of the original payment. This is the transfer that needs to be clawed back.

Example:

"550e8400-e29b-41d4-a716-446655440000"

lpIdentityPublicKey

string

required

Identity public key of the LP wallet where the funds were sent. This must be a valid LP wallet that exists in the system.

Example:

"03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"

nonce

string

required

Unique nonce for replay protection. Each clawback request must use a unique nonce.

Example:

"clawback-nonce-123456"

signature

string

required

Hex-encoded secp256k1 signature of the request. Must be signed by the private key corresponding to sender_public_key.

Example:

"3045022100a7e5d4f8b2c9a1e6f0d5b8c4a9e7f2d1c8b5a4e9f0d6c5b3a2e1d0c9b8a7f02201f2e3d4c5b6a7980e9f0a1b2c3d4e5f67889a0b1c2d3e4f5a6b7c8d9e0f1a2b3"

Response

Clawback accepted for processing

Response for a successful clawback request

requestId

string

required

Unique request ID for tracking this clawback

Example:

"01HJZKFABCDEFGHJKLMNPQRSTVW"

accepted

boolean

required

Whether the clawback was accepted for processing

Example:

true

internalRequestId

string

required

Internal request ID from the settlement service

Example:

"settlement-internal-123"

sparkStatusTrackingId

string

required

Spark status tracking ID for monitoring the refund

Example:

"spark-track-456"

flashnetRequestId

string | null

Settlement service request ID for correlation

Example:

"018D5E56-9D80-7890-A1B2-C3D4E5F6G7H8"

error

string | null

Optional error message if the clawback was rejected

Example:

"Transfer is too old for clawback"

Check Clawback Eligibility

Get Host Fee Withdrawal History

⌘I

Auth

Clawback

Hosts

Integrators

Liquidity

Status

Pools

Swaps

Clawback Funds

Eligibility Requirements

Process Flow

Important Notes

Authentication

Arguments

Returns

Authorizations

Body

Response