Transactions

Endpoints to obtain transaction details and to broadcast transactions to the network

Get block transactions

get

Retrieves transactions confirmed in a single block

Path parameters

height_or_hashany ofRequired

string · enumOptionalPossible values:

or

stringOptional

Block hash

Example: 0xdaf79950c5e8bb0c620751333967cdd62297137cdaf79950c5e8bb0c62075133Pattern: ^(0x)?[a-fA-F0-9]{64}$

or

integerOptional

Block height

Example: 777678

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index

Pattern: ^[0-9]+:[0-9]+:[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/blocks/{height_or_hash}/transactions

GET /extended/v3/blocks/{height_or_hash}/transactions HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "tx_id": "text",
      "sender": {
        "address": "text",
        "nonce": 1
      },
      "sponsor": {
        "address": "text",
        "nonce": 1
      },
      "fee_rate": "text",
      "block": {
        "height": 1,
        "hash": "text",
        "index_hash": "text",
        "time": 1,
        "tx_index": 1
      },
      "bitcoin_block": {
        "height": 1,
        "time": 1
      },
      "status": "success",
      "type": "token_transfer",
      "token_transfer": {
        "recipient": "text",
        "amount": "text",
        "memo": {
          "hex": "text",
          "repr": "text"
        }
      }
    }
  ]
}

Get principal transactions

get

Returns a list of confirmed transactions sent or received by a Stacks principal, including the transaction summary, the involvement of the principal in the transaction, and the balances affected by the transaction.

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index

Pattern: ^[0-9]+:[0-9]+:[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/transactions

GET /extended/v3/principals/{principal}/transactions HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "transaction": {
        "tx_id": "text",
        "sender": {
          "address": "text",
          "nonce": 1
        },
        "sponsor": {
          "address": "text",
          "nonce": 1
        },
        "fee_rate": "text",
        "block": {
          "height": 1,
          "hash": "text",
          "index_hash": "text",
          "time": 1,
          "tx_index": 1
        },
        "bitcoin_block": {
          "height": 1,
          "time": 1
        },
        "status": "success",
        "type": "token_transfer",
        "token_transfer": {
          "recipient": "text",
          "amount": "text",
          "memo": {
            "hex": "text",
            "repr": "text"
          }
        }
      },
      "involvement": "sender",
      "balance_changes": {
        "stx": {
          "sent": "text",
          "received": "text",
          "net": "text"
        }
      },
      "affected_balances": {
        "stx": true,
        "ft": true,
        "nft": true
      }
    }
  ]
}

Get inbound STX transfers

get

Returns the individual inbound STX events crediting a principal. Includes native stx-transfer transactions, send-many-memo bulk-send legs, any other STX transfer event crediting the principal, and STX mints (which have a null sender), each with its own sender, amount, and memo. A transaction that credits the principal multiple times yields one result per event.

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index

Pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/transfers/stx/inbound

GET /extended/v3/principals/{principal}/transfers/stx/inbound HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "sender": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "recipient": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "amount": "1000000",
      "memo": {
        "hex": "text",
        "repr": "text"
      },
      "transaction": {
        "tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
        "event_index": 1
      },
      "block": {
        "height": 1,
        "hash": "text",
        "index_hash": "text",
        "time": 1,
        "tx_index": 1
      }
    }
  ]
}

Get outbound STX transfers

get

Returns the individual outbound STX events debiting a principal. Includes native stx-transfer transactions, send-many-memo bulk-send legs, any other STX transfer event debiting the principal, and STX burns (which have a null recipient), each with its own recipient, amount, and memo. A transaction that debits the principal multiple times yields one result per event.

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index

Pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/transfers/stx/outbound

GET /extended/v3/principals/{principal}/transfers/stx/outbound HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "sender": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "recipient": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "amount": "1000000",
      "memo": {
        "hex": "text",
        "repr": "text"
      },
      "transaction": {
        "tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
        "event_index": 1
      },
      "block": {
        "height": 1,
        "hash": "text",
        "index_hash": "text",
        "time": 1,
        "tx_index": 1
      }
    }
  ]
}

Get fungible token transfers

get

Returns a principal's transfer history for a single fungible token as one feed, newest first, combining the events that credit it and the events that debit it. Includes mints (which have a null sender) and burns (which have a null recipient). A transaction that moves the token several times for this principal yields one result per event. Amounts are in the token's own base units.

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

asset_identifierstringRequired

Asset Identifier

Example: SP000000000000000000002Q6VF78.pox-3::stx-tokenPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}::[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*]){0,127}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index

Pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/transfers/ft/{asset_identifier}

GET /extended/v3/principals/{principal}/transfers/ft/{asset_identifier} HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "sender": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "recipient": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "amount": "1000000",
      "transaction": {
        "tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
        "event_index": 1
      },
      "block": {
        "height": 1,
        "hash": "text",
        "index_hash": "text",
        "time": 1,
        "tx_index": 1
      }
    }
  ]
}

Get principal transaction balance changes

get

Returns the balance changes for a principal's transaction

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

tx_idstringRequired

Transaction ID

Example: 0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6Pattern: ^(0x)?[a-fA-F0-9]{64}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating principal transaction balance changes. Format: <asset_type>:<asset_identifier> where asset_type is a numeric tag (1=STX, 2=FT, 3=NFT) and asset_identifier is <stx> for STX or a fully-qualified Clarity asset id such as SP000…contract-name::asset-name for FT/NFT.

Pattern: ^[0-9]+:\S+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/transactions/{tx_id}/balance-changes

GET /extended/v3/principals/{principal}/transactions/{tx_id}/balance-changes HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "asset": {
        "type": "stx"
      },
      "balance_change": {
        "sent": "text",
        "received": "text",
        "net": "text"
      }
    }
  ]
}

Get principal balance changes

get

Returns the balance changes for a principal across one or more transactions, as a single paginated flat array ordered by chain position descending then by asset.

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating principal balance changes across multiple transactions. Format: <block_height>:<microblock_sequence>:<tx_index>:<asset_type>:<asset_identifier>.

Pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+:\S+$

tx_idstring[] · min: 1 · max: 20Required

Transaction ids to query balance changes for. Provide as repeated querystring values (?tx_id=A&tx_id=B) or as a single comma-separated value (?tx_id=A,B).

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/balance-changes

GET /extended/v3/principals/{principal}/balance-changes?tx_id=0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6 HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
      "asset": {
        "type": "stx"
      },
      "balance_change": {
        "sent": "text",
        "received": "text",
        "net": "text"
      }
    }
  ]
}

Get principal mempool transactions

get

Returns a list of pending mempool transactions that involve a principal — as the sender, a token-transfer recipient, the deployed contract, or the called contract.

Path parameters

principalany ofRequired

stringOptional

Stacks Address

Example: SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

or

stringOptional

Smart Contract ID

Example: SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating mempool transactions. Format: receipt_time:tx_id

Pattern: ^\d+:(0x)?[a-fA-F0-9]{64}$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/principals/{principal}/mempool/transactions

GET /extended/v3/principals/{principal}/mempool/transactions HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "tx_id": "text",
      "sender": {
        "address": "text",
        "nonce": 1
      },
      "sponsor": {
        "address": "text",
        "nonce": 1
      },
      "fee_rate": "text",
      "receipt_time": 1,
      "receipt_block_height": 1,
      "status": "pending",
      "type": "token_transfer",
      "token_transfer": {
        "recipient": "text",
        "amount": "text",
        "memo": {
          "hex": "text",
          "repr": "text"
        }
      }
    }
  ]
}

Get transactions

get

Retrieves a list of recently mined transactions

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index

Pattern: ^[0-9]+:[0-9]+:[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 50Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/transactions

GET /extended/v3/transactions HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "tx_id": "text",
      "sender": {
        "address": "text",
        "nonce": 1
      },
      "sponsor": {
        "address": "text",
        "nonce": 1
      },
      "fee_rate": "text",
      "block": {
        "height": 1,
        "hash": "text",
        "index_hash": "text",
        "time": 1,
        "tx_index": 1
      },
      "bitcoin_block": {
        "height": 1,
        "time": 1
      },
      "status": "success",
      "type": "token_transfer",
      "token_transfer": {
        "recipient": "text",
        "amount": "text",
        "memo": {
          "hex": "text",
          "repr": "text"
        }
      }
    }
  ]
}

Get a batch of transactions

get

Retrieves the summaries of up to 20 mined transactions in a single call, given their transaction ids. Provide them as repeated querystring values (?tx_id=A&tx_id=B) or as a single comma-separated value (?tx_id=A,B). Results are returned in canonical chain order (newest first), not in the order the ids were supplied. Only transactions mined in the canonical chain are returned: an id that is unknown, non-canonical, or still in the mempool is absent from results rather than reported as an error, so compare the response against the ids you sent to find the ones that did not resolve. Use GET /extended/v3/transactions/{tx_id} for a single transaction, which also covers mempool transactions.

Query parameters

tx_idstring[] · min: 1 · max: 20Required

Transaction ids to fetch summaries for. Provide as repeated querystring values (?tx_id=A&tx_id=B) or as a single comma-separated value (?tx_id=A,B).

Responses

200

Default Response

application/json

4XX

Default Response

application/json

get/extended/v3/transactions/batch

GET /extended/v3/transactions/batch?tx_id=0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6 HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "results": [
    {
      "tx_id": "text",
      "sender": {
        "address": "text",
        "nonce": 1
      },
      "sponsor": {
        "address": "text",
        "nonce": 1
      },
      "fee_rate": "text",
      "block": {
        "height": 1,
        "hash": "text",
        "index_hash": "text",
        "time": 1,
        "tx_index": 1
      },
      "bitcoin_block": {
        "height": 1,
        "time": 1
      },
      "status": "success",
      "type": "token_transfer",
      "token_transfer": {
        "recipient": "text",
        "amount": "text",
        "memo": {
          "hex": "text",
          "repr": "text"
        }
      }
    }
  ]
}

Get transaction

get

Retrieves details for a given transaction, including both mined and mempool transactions

Path parameters

tx_idstringRequired

Transaction ID

Example: 0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6Pattern: ^(0x)?[a-fA-F0-9]{64}$

Query parameters

Responses

200

Default Response

application/json

or

or

or

or

or

or

or

or

or

or

or

4XX

Default Response

application/json

get/extended/v3/transactions/{tx_id}

GET /extended/v3/transactions/{tx_id} HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "tx_id": "text",
  "sender": {
    "address": "text",
    "nonce": 1
  },
  "sponsor": {
    "address": "text",
    "nonce": 1
  },
  "fee_rate": "text",
  "block": {
    "height": 1,
    "hash": "text",
    "index_hash": "text",
    "time": 1,
    "tx_index": 1
  },
  "bitcoin_block": {
    "height": 1,
    "time": 1
  },
  "status": "success",
  "parent_block": {
    "hash": "text",
    "index_hash": "text"
  },
  "post_condition_mode": "allow",
  "post_conditions": [
    {
      "principal": {
        "type_id": "principal_origin"
      },
      "condition_code": "sent_equal_to",
      "amount": "text",
      "type": "stx"
    }
  ],
  "event_count": 1,
  "execution_cost": {
    "read_count": 1,
    "read_length": 1,
    "runtime": 1,
    "write_count": 1,
    "write_length": 1
  },
  "vm_error": "text",
  "result": {
    "hex": "text",
    "repr": "text"
  },
  "type": "token_transfer",
  "token_transfer": {
    "recipient": "text",
    "amount": "text",
    "memo": {
      "hex": "text",
      "repr": "text"
    }
  }
}

Get transaction events

get

Retrieves events for a given transaction ID

Path parameters

tx_idstringRequired

Transaction ID

Example: 0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6Pattern: ^(0x)?[a-fA-F0-9]{64}$

Query parameters

limitinteger · min: 1 · max: 100Optional

Number of results per page

Default: 20

cursorstringOptional

Cursor for paginating transaction events. Format: event_index

Pattern: ^[0-9]+$

Responses

200

Default Response

application/json

totalintegerRequiredExample: 1

limitinteger · min: 1 · max: 100Required

Number of results per page

Default: 20

4XX

Default Response

application/json

get/extended/v3/transactions/{tx_id}/events

GET /extended/v3/transactions/{tx_id}/events HTTP/1.1
Host: api.hiro.so/
Accept: */*

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "event_index": 1,
      "type": "contract_log",
      "contract_log": {
        "contract_id": "SP000000000000000000002Q6VF78.pox-3",
        "topic": "print",
        "value": {
          "hex": "text",
          "repr": "text"
        }
      }
    }
  ]
}