> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /recover

> Get back the funds a failed Hinkal swap left at Hinkal.

A [Hinkal](https://docs.ravn.exchange/private-swaps.md#hinkal) swap whose payout fails isn't refunded on its own. This endpoint
sends the funds back to the wallet that paid, and only there. Use it when `/status` reports `failed`
with `venueStatus` ending `(needs recovery)`, or when the deposit confirmed but `/status` still says
`pending` 25 minutes after the order. It works for 7 days after the order.

> [!WARNING]
>
> **A recovery is public.** It's an ordinary on-chain payment back to the paying wallet, which can
> link that wallet to the one it was paying. Tell your user before they sign.

On JavaScript or TypeScript, [`recoverStuckFunds`](https://docs.ravn.exchange/sdks/core#recoverstuckfunds) runs the whole flow
and checks each step. In Python, use [`recover_stuck_funds`](https://docs.ravn.exchange/sdks/python#recover_stuck_funds).

## The flow

**1. Ask with the statusRef**

`{ statusRef }` answers `sign` step 1: a `personal_sign` that opens a read-only session. Check it
as on [`/execute`](https://docs.ravn.exchange/private-swaps#authorize-steps): the same three lines, never the extra
"can also be used to submit transactions" line.

**2. Prove the wallet paid**

Send `{ statusRef, authorization, signature }` signed by the paying wallet. It answers `sign`
step 2 (a recovery to sign) or `nothing`.

**3. Sign the recovery**

Check the typed data: domain `{ name: "Hinkal Enclave", chainId }` on the swap's source chain,
`primaryType` `RecoverStuckBridgeBalance` or `WithdrawStuckUtxos`, `message.chainId` equal to
the domain's, one `tokenAddress`, and `recipient` the paying wallet. Send `{ statusRef, authorization, signature }` again. It answers
`done` with what was recovered.

**4. Look again**

A swap can leave more than one token. Send `{ statusRef, authorization }` with the
`authorization` from `done` and no signature, until the answer is `nothing`.

Each `authorization` is single-use and lasts 10 minutes.

## Request

**statusRef** `string` *required*

The `statusRef` of the Hinkal swap's `TRANSACTION`.

**authorization** `string`

From the previous answer.

**signature** `string`

The paying wallet's signature over the previous answer's `sign`. Leave it out after `done`.

```bash theme={null}
curl -s -X POST https://app.ravn.exchange/api/v1/recover \
  -H 'content-type: application/json' \
  -d '{ "statusRef": "<the Hinkal TRANSACTION statusRef>" }'
```

## Response

```json sign theme={null}
{ "data": { "status": "sign", "authorization": "hk_…", "step": 1, "expiresAt": "2026-10-22T12:09:00.000Z",
    "sign": { "method": "personal_sign", "message": "Authorize Hinkal session\nSession ID: …\nPublic Key: …" } } }
```

```json done theme={null}
{ "data": { "status": "done", "authorization": "hk_…",
    "recovered": [{ "chainId": 8453, "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "49650000" }] } }
```

```json nothing theme={null}
{ "data": { "status": "nothing" } }
```

`recovered` amounts are before Hinkal's recovery fee, so the wallet receives slightly less.
`nothing` means nothing is stuck right now. A failed bridge shows up about 3 minutes after the
payout fails, so try again a few minutes later if you called too soon.

## Errors

| Code | Fix |
| - | - |
| `400 INVALID_REQUEST` | Not a Hinkal order id, a signature from the wrong wallet ("sign with the wallet that paid"), or an expired or used `authorization`: start again from step 1 |
| `429 RATE_LIMITED` | 30 calls an hour per IP, or 300 per key. Wait the minutes the message gives |
| `502 BUILD_FAILED` / `500 INTERNAL` | Hinkal can't be reached right now. Try again shortly |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.