Revocations

A revocation turns a deposit address back into a plain address by removing its delegation.

List revocations

GET/v1/revocations

Your revocations, newest first. The filters combine.

Parameters

Name	In	Type	Description
limit	query	integer	How many rows a page holds. From 1 to 200. Default: 50.
cursor	query	string	The next_cursor of the previous page; none for the first page.
status	query	string	Only revocations with this status. One of: queued, processing, revoked, failed, rejected.
chain_id	query	ChainID	Only this chain.
account	query	Address	Only revocations of this deposit address.

Responses

Status	Description
200	A page of revocations. Returns the fields below.
400	invalid_query: a query parameter is not valid; message says which.
401	unauthorized: no API key, an unknown one or a revoked one.
403	partner_disabled: your account is disabled.

Response body

Field	Type	Description
items required	array of Revocation
next_cursor required	NextCursor	The cursor of the next page; null on the last page.

Example request

curl "https://api-testnet.portuna.io/v1/revocations?account=0x2c7536E3605D9C16a7a3D7b1898e529396a65c23" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Example response

200 OK

{
  "items": [
    {
      "id": "5e9b1c27-3f6d-4a08-8c2e-71d4a0b9f356",
      "external_id": "revoke-2c75",
      "chain_id": 11155111,
      "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
      "status": "revoked",
      "attempts": 1,
      "tx_hash": "0x452b10b75c363823e1fa24b25d89bdaf2c7e3237deacc5260991627ee49954e3",
      "gas": 28800,
      "gas_cost": "34560000000000",
      "created_at": "2026-10-12T10:00:00Z",
      "updated_at": "2026-10-12T10:00:37Z"
    }
  ],
  "next_cursor": null
}

Revoke a delegation

POST/v1/revocations

Turns a deposit address back into a plain address. The deposit address signs an authorization of the zero address, and your gas wallet sends it in a transaction to itself. The gas comes from your gas wallet, with no fee. A revocation waits for the sweeps of the same deposit address requested before it. Sign with the deposit address’s nonce as it will be when the revocation is sent: if a sweep with an authorization goes on chain first, the nonce grows by 1. The outcome comes in a revocation.revoked, revocation.failed or revocation.rejected webhook event and shows in GET /v1/revocations/{id}. To sweep the address again later, it needs a new authorization of the delegate.

Request body

Field	Type	Description
external_id	string	Your id for the revocation, unique in your account: a request with an external_id that is already taken returns that revocation instead of creating another, so retries are safe. Up to 128 characters.
chain_id required	ChainID	The chain’s id (EIP-155): 11155111 Sepolia and 97 BSC testnet with a test key, 1 Ethereum and 56 BSC with a live key.
account required	Address	The deposit address.
authorization required	Authorization	The deposit address’s authorization with address = 0x0000000000000000000000000000000000000000.
authorization.chain_id required	integer (int64)	The chain of the request; 0 (any chain) is refused.
authorization.address required	Address	The hot wallet’s delegate from POST /v1/hot-wallets; the zero address for a revocation.
authorization.nonce required	integer (int64)	The deposit address’s current nonce.
authorization.y_parity required	integer	The signature’s y parity. One of: 0, 1.
authorization.r required	string	The signature’s r, 0x-hex of up to 32 bytes. Format: ^0x[0-9a-fA-F]{1,64}$.
authorization.s required	string	The signature’s s, 0x-hex of up to 32 bytes, in the lower half of the curve order (EIP-2). Format: ^0x[0-9a-fA-F]{1,64}$.

Responses

Status	Description
200	A revocation with this external_id already exists. It is returned as it is now, and no other revocation is created. Returns Revocation.
202	The revocation is queued. Returns Revocation.
400	invalid_json: the body is not JSON, is over 64 KiB or has unknown fields.
401	unauthorized: no API key, an unknown one or a revoked one.
403	partner_disabled: your account is disabled.
422	unknown_chain, invalid_external_id, invalid_address or invalid_authorization (also when authorization is missing); message says what is wrong.

Example request

curl -X POST "https://api-testnet.portuna.io/v1/revocations" \
  -H "Authorization: Bearer $PORTUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "revoke-2c75",
  "chain_id": 11155111,
  "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "authorization": {
    "chain_id": 11155111,
    "address": "0x0000000000000000000000000000000000000000",
    "nonce": 1,
    "y_parity": 1,
    "r": "0x04bec751666b1f63d7f4572d81a38642d47517b63b84f6b94a0a494a198c315d",
    "s": "0x2a3cc8c27acdae37a0eb652d394ff698ad3910adbfa4d7a393c49a6d4099cabb"
  }
}'

Example response

202 Accepted

{
  "id": "5e9b1c27-3f6d-4a08-8c2e-71d4a0b9f356",
  "external_id": "revoke-2c75",
  "chain_id": 11155111,
  "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "status": "queued",
  "attempts": 0,
  "created_at": "2026-10-12T10:00:00Z",
  "updated_at": "2026-10-12T10:00:00Z"
}

Get a revocation

GET/v1/revocations/{id}

Parameters

Name	In	Type	Description
id required	path	string (uuid)	The revocation’s id.

Responses

Status	Description
200	The revocation. Returns Revocation.
401	unauthorized: no API key, an unknown one or a revoked one.
403	partner_disabled: your account is disabled.
404	not_found: there is no such object in your account.

Example request

curl "https://api-testnet.portuna.io/v1/revocations/5e9b1c27-3f6d-4a08-8c2e-71d4a0b9f356" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Example response

200 OK

{
  "id": "5e9b1c27-3f6d-4a08-8c2e-71d4a0b9f356",
  "external_id": "revoke-2c75",
  "chain_id": 11155111,
  "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "status": "revoked",
  "attempts": 1,
  "tx_hash": "0x452b10b75c363823e1fa24b25d89bdaf2c7e3237deacc5260991627ee49954e3",
  "gas": 28800,
  "gas_cost": "34560000000000",
  "created_at": "2026-10-12T10:00:00Z",
  "updated_at": "2026-10-12T10:00:37Z"
}