Idempotency

A request can time out after the service has accepted it. To retry without creating a second sweep, give every sweep an external_id: your own id for it, such as the id of the deposit in your system.

{ "external_id": "dep-7f3a91", "chain_id": 11155111, "hot_wallet": "0x…", "account": "0x…", "token": "USDT" }

• The first request with an external_id creates the sweep and answers 202 Accepted.
• Any later request with the same external_id creates nothing and answers 200 OK with the sweep created the first time, whatever its status now. The SDKs return it with created: false.
• external_id is up to 128 characters, unique among all your sweeps. Revocations have their own external_ids, separate from the sweeps’.

Caution

The service does not compare the request bodies: a request with a used external_id returns the original sweep even if the rest of it differs. Use one external_id per sweep you mean to make, and a new one for the next sweep of the same address.

A request is validated before the external_id is looked up: a retry with an invalid body gets its error, not the original sweep.

Without external_id

Each request creates a new sweep. A retry after a timeout can then queue the same sweep twice. Without amount, the second one usually finds nothing left and is rejected; with an amount, it can move more than you meant if the address received new funds in between. Always set external_id.

Retrying safely

• Network errors, timeouts and 5xx: retry with the same external_id, with a growing pause.
• 4xx: do not retry the same request: fix what the error says. See Errors and retries.
• A sweep that ended rejected or failed: it is final. To try again, for example with a new authorization, send a new request with a new external_id.

Idempotent by nature

Request	Repeating it
POST /v1/hot-wallets	Returns the same hot wallet for the same chain and address. After failed it restarts the deployment.
PUT /v1/webhook	Sets the same settings again; the secret stays.
PATCH /v1/settings	Sets the same values again.
DELETE /v1/webhook	Answers 404 not_found and changes nothing.
GET requests	Change nothing.

POST /v1/webhook/test is not idempotent: each call queues another test event.