Objects

The objects the API returns and accepts. Fields that are not required are left out of a response when they have no value.

Error

Field	Type	Description
error required	object
error.code required	string	What went wrong. Stable, so branch on it.
error.message required	string	The details, for people. It may change.

Address

A 0x-hex address, in any case in requests and checksummed (EIP-55) in responses.

Type: string. Format: ^0x[0-9a-fA-F]{40}$. Example: 0x2Cd50979a8A33e8CA37DA85F8517fb148a67b769.

Amount

An integer in the smallest units, as a string.

Type: string. Format: ^[0-9]+$. Example: 1000000.

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.

Type: integer (int64). Example: 11155111, 97.

Gas

An amount of gas.

Type: integer (int64).

NextCursor

The cursor of the next page; null on the last page.

Type: string \| null.

LedgerKind

gas: the gas of a transaction of your gas wallet; fee: the fee for a sweep; fee_charge: a charge made under your agreement; fee_credit: a credit made under your agreement, which reduces the fees due; withdrawal: fees withdrawn from the gas wallet, together with the withdrawal’s gas; topup: a top-up of the gas wallet, found by the balance reconciliation.

Type: string.

LedgerEntry

A change of your gas wallet’s balance, or of the fees it holds.

Field	Type	Description
id required	integer (int64)
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.
kind required	LedgerKind	gas: the gas of a transaction of your gas wallet; fee: the fee for a sweep; fee_charge: a charge made under your agreement; fee_credit: a credit made under your agreement, which reduces the fees due; withdrawal: fees withdrawn from the gas wallet, together with the withdrawal’s gas; topup: a top-up of the gas wallet, found by the balance reconciliation. One of: gas, fee, fee_charge, fee_credit, withdrawal, topup.
amount required	string	Wei with a sign: plus for topup and fee_credit, minus for gas, fees, charges and withdrawals. Format: ^-?[0-9]+$.
tx_hash required	string | null	The transaction of the entry; null for top-ups, charges and credits.
sweep_id required	string | null (uuid)	The sweep a fee is for; null for other kinds.
note required	string | null	A note on charges and credits; for top-ups, the blocks the reconciliation covered.
created_at required	string (date-time)

UsageDay

Your activity on one chain in one UTC day.

Field	Type	Description
date required	string (date)	The UTC day.
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.
sweeps_done required	integer	Sweeps created that day that ended swept.
sweeps_failed required	integer	Sweeps created that day that ended failed, having reverted on chain or run out of attempts.
sweeps_rejected required	integer	Sweeps created that day that ended rejected: they were never sent, because a check before sending kept failing.
revocations_done required	integer	Revocations created that day that ended revoked.
gas_spent required	Amount	The gas of your gas wallet’s transactions that day, in wei, fee withdrawals aside.
fees required	string	Fees and charges accrued that day minus credits, in wei; below zero when the credits exceed them. Format: ^-?[0-9]+$.

WebhookDelivery

A webhook event and how its delivery went.

Field	Type	Description
id required	string (uuid)	The event’s id, as in the delivery.
event required	string	The event type.
status required	string	pending: being delivered, or waiting for the next attempt; delivered: your endpoint answered with a 2xx; failed: the attempts ran out, or the webhook was deleted. One of: pending, delivered, failed.
attempts required	integer	Attempts made so far.
last_status_code required	integer | null	The HTTP status your endpoint answered the last attempt with; null if it did not answer.
last_error required	string | null	Why the last attempt failed; null if it did not. status <code>: your endpoint answered with another status. timeout, connection refused, connection reset, connection closed, DNS lookup failed, TLS error, connection failed: it did not answer; private address refused: its host resolves to an address that is not public. webhook removed: the webhook was deleted. internal: a failure on our side.
created_at required	string (date-time)	When the event happened.
delivered_at required	string | null (date-time)	When the event was delivered; null until then.
next_attempt_at required	string | null (date-time)	When the next attempt is due; only for pending.

Balance

Your gas wallet and its balance on each chain.

Field	Type	Description
gas_wallet required	Address	Your gas wallet, the same address on every chain.
chains required	array of object
chains[].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.
chains[].name required	string	The chain’s name.
chains[].native required	string	The ticker of the chain’s native coin.
chains[].balance	Amount	The gas wallet’s balance, in wei; absent when error is set.
chains[].fees_accrued required	Amount	All fees and charges accrued on this chain minus credits, in wei.
chains[].fees_withdrawn required	Amount	Fees withdrawn so far, with the gas of their withdrawals, in wei.
chains[].fees_due required	Amount	Fees accrued and not withdrawn yet, in wei. They stay on the gas wallet in reserve.
chains[].available	Amount	What is left for gas, in wei: balance minus fees_due, but not below zero. Absent when error is set.
chains[].error	string	chain_unavailable: the chain’s node did not answer, so there is no balance. One of: chain_unavailable.

ChainTariff

Your rates and the gas benchmarks on one chain.

Field	Type	Description
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.
name required	string	The chain’s name.
rate_bps required	integer	X for token sweeps, in basis points, 7000 = 70%; 0 means no fee.
rate required	string	rate_bps in percent.
native_markup_bps required	integer	The markup on gas for native coin sweeps, in basis points.
native_markup required	string	native_markup_bps in percent.
classic_gas	map of object	The classic benchmark of each asset, by the token’s ticker or the native coin’s: the gas of topping up a deposit address and transferring from it. Absent on a chain without benchmarks.
classic_gas.<key>.new required	Gas	Gas for an address without an account on the chain, which the top-up creates (tokens only).
classic_gas.<key>.existing required	Gas	Gas for an address with an account.
extra_gas	object	The batch gas a first sweep of an address bears on top of a repeat one. Absent on a chain without benchmarks.
extra_gas.delegation required	Gas	Setting the address’s delegate by its authorization.
extra_gas.account required	Gas	Creating the address’s account as well, for an address that held only tokens.

Settings

Field	Type	Description
keep_one_unit	boolean	Token sweeps leave 1 smallest unit on the deposit address, which makes your user’s next deposit cheaper. A sweep request can override it. Off by default.

HotWallet

A hot wallet on one chain and its delegate.

Field	Type	Description
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.
address required	Address	The hot wallet, where sweeps send the funds.
delegate required	Address	The hot wallet’s delegate, the address deposit addresses sign their authorizations for.
status required	string	pending: the delegate is being deployed; active: it is deployed, and sweeps can go; failed: the deployment failed, and registering the hot wallet again retries it. One of: pending, active, failed.
error	string	Why the deployment failed; only with failed. Most often insufficient_gas_balance: top up the gas wallet and register the hot wallet again. not_deployed: the deployment went through, but the delegate is not there. The other codes are the causes of a failed attempt, as in a sweep’s reason. One of: not_deployed, insufficient_gas_balance, gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable, internal.
tx_hash	string	The transaction that deployed the delegate.
created_at required	string (date-time)	When the hot wallet was registered.

Authorization

An EIP-7702 authorization signed by the deposit address’s key: on chain chain_id, the deposit address runs the code at address. How to sign it, also in an HSM, a KMS or an MPC wallet: the Signing authorizations guide in the developer documentation.

Field	Type	Description
chain_id required	integer (int64)	The chain of the request; 0 (any chain) is refused.
address required	Address	The hot wallet’s delegate from POST /v1/hot-wallets; the zero address for a revocation.
nonce required	integer (int64)	The deposit address’s current nonce.
y_parity required	integer	The signature’s y parity. One of: 0, 1.
r required	string	The signature’s r, 0x-hex of up to 32 bytes. Format: ^0x[0-9a-fA-F]{1,64}$.
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}$.

SweepRequest

What to sweep, from where and to where.

Field	Type	Description
external_id	string	Your id for the sweep, unique in your account: a request with an external_id that is already taken returns that sweep 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.
hot_wallet required	Address	Your hot wallet on this chain; its delegate must be active.
account required	Address	The deposit address.
token required	string	A token’s ticker listed on the chain (in any case), the contract address of a listed token, or native (or the native coin’s ticker) for the native coin.
amount	Amount	How much to sweep, above zero; without it, the whole balance.
keep_one_unit	boolean	Leave 1 smallest unit of the token on the deposit address; defaults to your settings. Ignored for the native coin.
authorization	Authorization	Needed until the deposit address is delegated to this hot wallet’s delegate. After that it is not used, though one that is sent must still be valid.

Sweep

A sweep and its outcome.

Field	Type	Description
id required	string (uuid)
external_id	string	Your id for the sweep, if the request had one.
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.
hot_wallet required	Address	The hot wallet.
account required	Address	The deposit address.
token required	string	The token’s ticker, or the native coin’s.
token_address	Address	The token’s contract address; absent for the native coin.
amount	Amount	The amount requested; absent when the request was for the whole balance.
keep_one_unit	boolean	Present and true when the sweep leaves 1 smallest unit of the token on the deposit address.
status required	string	queued: waiting for a batch or a retry; processing: in a batch being prepared, sent or confirmed; swept: done, the funds are in the hot wallet; failed: reverted on chain, or ran out of attempts; rejected: never sent. The last three are final. One of: queued, processing, swept, failed, rejected.
reason	string	Why the sweep ended rejected or failed, or, while it is queued for a retry, why the last attempt did not go through. A stable code: the node’s own messages stay in our logs. - rejected, a check before sending kept failing: not_upgraded, stale_authorization, would_fail or nothing_to_sweep. - failed on chain, inside a batch that went through: the contract error the transfer reverted with, TokenTransferFailed, NativeTransferFailed, NothingToSweep or Unauthorized, or reverted without one. - The cause of a failed attempt, which is retried, and final with failed once the attempts run out: insufficient_gas_balance (top up the gas wallet), gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable or internal. One of: not_upgraded, stale_authorization, would_fail, nothing_to_sweep, reverted, TokenTransferFailed, NativeTransferFailed, NothingToSweep, Unauthorized, insufficient_gas_balance, gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable, internal.
attempts required	integer	How many times the sweep was tried.
swept_amount	Amount	How much reached the hot wallet; only with swept.
tx_hash	string	The batch transaction that carried the sweep.
kind	string	What the deposit address needed in the batch, which decides its share of the gas and the benchmark. repeat: nothing, it was already delegated. first: its delegation; it already had an account on the chain. first_new: its delegation, which also created its account, as it held only tokens. One of: repeat, first, first_new.
gas	Gas	The sweep’s share of the batch gas.
gas_cost	Amount	The same in wei.
fee	Amount	The fee in wei; only with swept.
classic_gas	Gas	The benchmark the fee was computed with.
rate_bps	integer	The rate the fee was computed with; for the native coin, the markup on gas.
created_at required	string (date-time)	When the sweep was requested.
updated_at required	string (date-time)	When the sweep last changed.

RevocationRequest

Which deposit address to revoke, with its authorization of the zero address.

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.

Revocation

A revocation and its outcome.

Field	Type	Description
id required	string (uuid)
external_id	string	Your id for the revocation, if the request had one.
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.
status required	string	queued and processing: as for a sweep; revoked: the deposit address has no delegation any more; failed: the transaction went through but the chain skipped the authorization, or the attempts ran out; rejected: never sent. The last three are final. One of: queued, processing, revoked, failed, rejected.
reason	string	Why the revocation ended rejected or failed, or, while it is queued for a retry, why the last attempt did not go through. For rejected: not_delegated (there is no delegation to remove), stale_authorization (the deposit address’s nonce has changed) or invalid_authorization. For failed: not_applied (the chain skipped the authorization). The other codes are the causes of a failed attempt, as in a sweep’s reason. One of: not_delegated, stale_authorization, invalid_authorization, not_applied, insufficient_gas_balance, gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable, internal.
attempts required	integer	How many times the revocation was tried.
tx_hash	string	The transaction that carried the revocation.
gas	Gas	The revocation’s share of its transaction’s gas.
gas_cost	Amount	The same in wei.
created_at required	string (date-time)	When the revocation was requested.
updated_at required	string (date-time)	When the revocation last changed.

Webhook

Your webhook settings.

Field	Type	Description
url required	string (uri)	Where events go.
secret required	string	The signing secret, whsec_…. Keep it on your backend.
low_balance required	array of object	Low balance alerts of your gas wallet, one per chain.
low_balance[].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.
low_balance[].threshold required	Amount	The threshold, in wei.
low_balance[].low required	boolean	The balance is below the threshold, and the alert was sent; it re-arms once the balance recovers.

Event

The body of a webhook delivery. type tells what happened and what data is: a sweep as in GET /v1/sweeps/{id}, a revocation as in GET /v1/revocations/{id}, a hot wallet as in GET /v1/hot-wallets, a low balance alert or a test event. Sweeps, revocations and hot wallets are shown as they are when the event is delivered.

One of SweepEvent, RevocationEvent, HotWalletEvent, BalanceLowEvent, WebhookTestEvent; type tells which.

SweepEvent

A sweep ended. sweep.swept: it moved the funds; sweep.failed: it reverted on chain or ran out of attempts; sweep.rejected: it was never sent.

Field	Type	Description
id required	string (uuid)	The event’s id, the same in every attempt.
type required	string	The event type. One of: sweep.swept, sweep.failed, sweep.rejected.
created_at required	string (date-time)	When the event happened.
data required	Sweep	A sweep and its outcome.

RevocationEvent

A revocation ended. revocation.revoked: the delegation is removed; revocation.failed: the chain skipped the authorization, or the attempts ran out; revocation.rejected: it was never sent.

Field	Type	Description
id required	string (uuid)	The event’s id, the same in every attempt.
type required	string	The event type. One of: revocation.revoked, revocation.failed, revocation.rejected.
created_at required	string (date-time)	When the event happened.
data required	Revocation	A revocation and its outcome.

HotWalletEvent

A hot wallet’s delegate deployment ended. hot_wallet.active: the delegate is deployed; hot_wallet.failed: the deployment failed.

Field	Type	Description
id required	string (uuid)	The event’s id, the same in every attempt.
type required	string	The event type. One of: hot_wallet.active, hot_wallet.failed.
created_at required	string (date-time)	When the event happened.
data required	HotWallet	A hot wallet on one chain and its delegate.

BalanceLowEvent

Your gas wallet fell below a low balance threshold. One event each time it falls below; the alert re-arms once the balance recovers.

Field	Type	Description
id required	string (uuid)	The event’s id, the same in every attempt.
type required	string	The event type. One of: balance.low.
created_at required	string (date-time)	When the event happened.
data required	BalanceLow	A low balance alert.

WebhookTestEvent

The test event you asked for with POST /v1/webhook/test.

Field	Type	Description
id required	string (uuid)	The event’s id, the same in every attempt.
type required	string	The event type. One of: webhook.test.
created_at required	string (date-time)	When the event happened.
data required	WebhookTest	The data of a test event.

BalanceLow

A low balance alert.

Field	Type	Description
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.
gas_wallet required	Address	Your gas wallet.
balance required	Amount	Its balance on this chain when the alert fired, in wei.
threshold required	Amount	The threshold it fell below, in wei.

WebhookTest

The data of a test event.

Field	Type	Description
message required	string