Operations

Retrieving operations for an address.

Use the following endpoint to retrieve all operations for a user.

Endpoint

GET /operations/:address

Request Parameters

Name

Type

Required

Description

address

String

Yes

address associated with an operation

Example Request

The following request returns all operations associated with a Hyperliquid user a6f1E...0132

curl -X GET https://api.hyperunit-testnet.xyz/operations/0xa6f1Ef42D335Ec7CbfC39f57269c851568300132

200: OK Successful Response

{
  "addresses": [
    {
      "sourceCoinType": "bitcoin",
      "destinationChain": "hyperliquid",
      "address": "tb1pncsdk2979x2nksu5mvf9uu6z0v0a7632ss5vuw3fu4wv8805d09sjd7m3e",
      "signatures": {
        "field-node": "KU9w0QF1/lJECrkPSz8ssUmcWpD6ZshftuONYSO/ockUgeovGgmAPKbBBBLt4A0X0WsqaTaFYwEQcRyTGp7xWQ==",
        "hl-node-testnet": "/lElUTMr/4q7QBV6fur2b4LqV7c9DCMDHnMZiC73XO5WOfy46Q+t+2ZmbiPCaW7THLW9r13otiVCjeb/zAfAKA==",
        "node-1": "PXtxH2B/KtCaceEeAD9/pZ37c+Ryv4FmdC7QeN1AB+D1HzjhDtJs75P4Xi3YQB4pP46ycyZkhXnz65AJvFahuA=="
      }
    },
    {
      "sourceCoinType": "ethereum",
      "destinationChain": "hyperliquid",
      "address": "0xf040d1E1e7BCDc9947E5F7871c7F205786CcC494",
      "signatures": {
        "field-node": "6DTX4nLPd8+hYb2aJNowdu3R3J6nsXmGnhOYnaKIiSC7h6w3evgUzWI6rKG3CmjrjA5s3+X2cqNmlSfGMo+z2w==",
        "hl-node-testnet": "bc4Z8k3y+FHsiB2Fzus/wqBRAbtrgvlrgVVWJ4dT7DMVoGF4c+Jd69Rk7uJMelLf31xjJdtxmtdCHwDVT5ryjw==",
        "node-1": "BoEW/3Za0+j+wi1NlbXYrRsgywJhLyDrawToSCQkpYwnwB9GVFnxBoEb4a57HhpX8LnJfrPxN51eS0PHZS73Zw=="
      }
    }
  ],
  "operations": [
    {
      "opCreatedAt": "2025-03-12T23:42:27Z"",
      "operationId": "",
      "protocolAddress": "tb1pncsdk2979x2nksu5mvf9uu6z0v0a7632ss5vuw3fu4wv8805d09sjd7m3e",
      "sourceAddress": "tb1qkwl2vjeplzj76qz544qzenl26w0fscsfmxlews",
      "destinationAddress": "",
      "sourceChain": "bitcoin",
      "destinationChain": "hyperliquid",
      "sourceAmount": "10000000",
      "destinationFeeAmount": "0",
      "sweepFeeAmount": "0",
      "stateStartedAt": "0001-01-01T00:00:00Z",
      "stateUpdatedAt": "0001-01-01T00:00:00Z",
      "stateNextAttemptAt": "0001-01-01T00:00:00Z",
      "sourceTxHash": "1c6f6abc977ec3ba381ad99f3903a258eaae366adf7c7a7627ef159357cd67a6",
      "sourceTxConfirmations": 0,
      "destinationTxHash": "",
      "asset": "btc",
      "state": "sourceTxDiscovered"
    },
    {
      "opCreatedAt": "2025-03-12T23:40:49.279929Z",
      "operationId": "914ea76e4329845f9c1e03c87b66bc339dd9a8789ce9be7a46170d68e70dd791:0",
      "protocolAddress": "tb1pncsdk2979x2nksu5mvf9uu6z0v0a7632ss5vuw3fu4wv8805d09sjd7m3e",
      "sourceAddress": "tb1qkwl2vjeplzj76qz544qzenl26w0fscsfmxlews",
      "destinationAddress": "0xa6f1Ef42D335Ec7CbfC39f57269c851568300132",
      "sourceChain": "bitcoin",
      "destinationChain": "hyperliquid",
      "sourceAmount": "10000000",
      "destinationFeeAmount": "0",
      "sweepFeeAmount": "0",
      "stateStartedAt": "2025-03-12T23:40:49.465291Z",
      "stateUpdatedAt": "2025-03-12T23:40:49.465291Z",
      "stateNextAttemptAt": "2025-03-12T23:42:50.804735Z",
      "sourceTxHash": "914ea76e4329845f9c1e03c87b66bc339dd9a8789ce9be7a46170d68e70dd791:0",
      "sourceTxConfirmations": 1,
      "asset": "btc",
      "state": "waitForSrcTxFinalization"
    },
    {
      "opCreatedAt": "2025-03-12T23:38:02.019431Z",
      "operationId": "0x2ebf75c61e1c78f89b8e04f1af6912ca46c936293920fb320f8e8ca3eda360f3:0",
      "protocolAddress": "0xf040d1E1e7BCDc9947E5F7871c7F205786CcC494",
      "sourceAddress": "0xa6f1Ef42D335Ec7CbfC39f57269c851568300132",
      "destinationAddress": "0xa6f1Ef42D335Ec7CbfC39f57269c851568300132",
      "sourceChain": "ethereum",
      "destinationChain": "hyperliquid",
      "sourceAmount": "100000000000000000",
      "destinationFeeAmount": "454545454545454",
      "sweepFeeAmount": "140761861078.125",
      "stateStartedAt": "2025-03-12T23:40:40.798707Z",
      "stateUpdatedAt": "2025-03-12T23:40:40.798707Z",
      "stateNextAttemptAt": "2025-03-12T23:40:40.798698Z",
      "sourceTxHash": "0x2ebf75c61e1c78f89b8e04f1af6912ca46c936293920fb320f8e8ca3eda360f3:0",
      "destinationTxHash": "0xdC78799911e46bacA335e6c5BA50dA89e9885520:1741822714587",
      "broadcastAt": "2025-03-12T23:38:46.170519Z",
      "asset": "eth",
      "state": "done"
    }
  ]
}

400: Error Response

{"error":"Invalid input address"}

Operation Structure

Unit Operations include both deposits and withdrawals, and are returned as follows:

export type Operation = {
  /** Unique identifier, equivalent to sourceTxHash */
  operationId: string;
  /** ISO 8601 timestamp */
  opCreatedAt: string;

  /** Addresses */
  protocolAddress: string;
  sourceAddress: string;
  destinationAddress: string;

  /** Chain identifiers */
  sourceChain: 'bitcoin' | 'hyperliquid' | 'ethereum';
  destinationChain: 'bitcoin' | 'hyperliquid' | 'ethereum';

  /** Amounts, in smallest native units of source currency (satoshis/ wei) */
  // e.g. ethereum - 18 decimals, solana - 9 decimals, bitcoin - 8 decimals, pump - 6 decimals
  sourceAmount: string;
  destinationFeeAmount: string;
  sweepFeeAmount: string;

  /** Current operation status */
  state: OperationState;

  /** Source chain transaction hash */
  sourceTxHash: string;

  /** Destination chain transaction hash (empty until created) */
  destinationTxHash: string;

  /** Position in withdraw queue (0 if state != "wait_for_sweep") */
  positionInWithdrawQueue: number;

  /** asset being transferred (btc, eth, sol, fart). It's 
  possible that there are multiple assets per chain (i.e solana) */
  asset: string;
};

export type Address = {
  /** coin-type of the protocolAddress's source chain according to
   SLIP-44 (BITCOIN, ETHEREUM) **/
  sourceCoinType: string;
  
  /** destination chain of the protocol address **/
  destinationChain: string;
  
  /** the protocol address **/
  address: string;
  
  /** guardian signatures over the protocol address **/
  [key: string]: string;
};

Response Fields

opCreatedAt: The time at which the Unit protocol created a deposit/withdrawal operation corresponding to a given source transaction. The response is sorted by this timestamp in descending order.
This field will reflect the server's current timestamp when the corresponding operation has not yet been created (operationId will be empty). This may be the case for newly discovered & unconfirmed transactions, as Unit operations are created after a certain number of source confirmations:
- Bitcoin: 1 confirmation
- Ethereum: 8 confirmations
- Hyperliquid:1 confirmation
sourceTxConfirmations: The number of block confirmations of the source transaction. If this value is omitted from the response, the source transaction has reached finalization.
destinationTxConfirmations: The number of block confirmations of the destination transaction, applicable to operations in states QueuedForWithdraw and WaitForDstTxFinalization A value ≥ 1 signals that the recipient has received the funds on the destination network.
broadcastAt: The server-side timestamp of when the destination transaction was broadcasted, applicable to operations in states BroadcastTx and WaitForDstTxFinalization.
addresses: The Unit-generated protocolAddresses associated with the destination address given in /operations/:address
- sourceCoinType: this is the SLIP-44 coin-type associated with the chain that the protocolAddress is on (Ethereum, Bitcoin).
- address: this is the protocolAddress on the source-chain.

Additional Notes

Unit does not collect revenue from deposits / withdrawals. All "fees" associated with an operation are those necessaryy to process the source and destination transactions on their respective networks.
- destinationFeeAmount is the fee paid by the guardians to process the destination transaction on the destination chain (Hyperliquid for deposits, Bitcoin for withdrawals).
- sweepFeeAmount is the fee paid by the guardians to "sweep" funds on the source chain for the fulfillment of future operations by the Unit treasury. Because this fee is deducted from the operation amount prior to sweep execution, the amount deducted by Unit is an estimate. This estimate may differ slightly from the actual fee later paid by guardians to the source chain.
Unit transaction hashes are formatted as follows
- For Bitcoin transactions <txid>:<vout>
- For Ethereum transactions <tx-hash>:<trace-id>
- For Hyperliquid transactions <sender_address>:<nonce>
- For Solana transactions <signature>:<destination-address>
Any operation that has yet to reach 2 bitcoin confirmations (whether discovered in a block or not) will be returned with the srcTxDiscovered state.

Operation States

An operation can be in one of the following states

/** Represents the current status of an operation */
enum OperationState {
  SrcTxDiscovered = 'sourceTxDiscovered',
  WaitForSrcTxFinalization = 'waitForSrcTxFinalization',
  BuildingDstTx = 'buildingDstTx',
  SignTx = 'signTx',
  BroadcastTx = 'broadcastTx',
  WaitForDstTxFinalization = 'waitForDstTxFinalization',
  ReadyForWithdrawQueue = 'readyForWithdrawQueue',
  QueuedForWithdraw = 'queuedForWithdraw',
  Done = 'done',
  Failure = 'failure',
}

The permutation of states differs slightly between deposits and withdrawals, as explained in depth in their lifecycles.

PreviousEstimate Fees NextDeposit Lifecycle

Last updated 1 month ago