diff --git a/components/sandbox.yaml b/components/sandbox.yaml
index f96b346c..f1e58753 100644
--- a/components/sandbox.yaml
+++ b/components/sandbox.yaml
@@ -15,4 +15,5 @@ Category:
- private-transactions
- notify
- transaction-simulation
+ - transactions
# - accounts
diff --git a/evm_body.yaml b/evm_body.yaml
index b063ebe6..e11b6c0f 100644
--- a/evm_body.yaml
+++ b/evm_body.yaml
@@ -1355,6 +1355,86 @@ alchemy_getAssetTransfers:
type: string
description: 'String - UUID for pagination. If more results are available, a uuid pageKey will be returned in the response. Pass that uuid into pageKey to fetch the next 1000 or maxCount.'
+# ============= Txn History API Methods ===============
+by-address:
+ allOf:
+ - $ref: '#/common_request_fields'
+ - type: object
+ properties:
+ method:
+ $ref: ./components/schemas.yaml#/Method
+ default: by-address
+ params:
+ type: array
+ minItems: 1
+ maxItems: 1
+ items:
+ type: object
+ required:
+ - category
+ properties:
+ fromBlock:
+ type: string
+ description: 'String - Inclusive from block (hex string, int, `latest`, or `indexed`). Defaults to `0x0`'
+ default: '0x0'
+ toBlock:
+ type: string
+ description: 'String - Inclusive to block (hex string, int, `latest`, or `indexed`). Defaults to `latest`. Read more about block tags here'
+ default: latest
+ fromAddress:
+ type: string
+ description: String - From address (hex string). Default wildcard - any address
+ pattern: '^0[xX][0-9a-fA-F]+$'
+ toAddress:
+ type: string
+ description: String - To address (hex string). Default wildcard - any address
+ pattern: '^0[xX][0-9a-fA-F]+$'
+ default: '0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1'
+ contractAddresses:
+ type: array
+ description: 'String - List of contract addresses (hex strings) to filter for - only applies to "erc20", "erc721", "erc1155" transfers. Default wildcard - any address'
+ items:
+ type: string
+ pattern: '^0[xX][0-9a-fA-F]+$'
+ category:
+ type: array
+ minItems: 1
+ description: |
+ 'Array of categories, can be any of the following: "external", "internal", "erc20", "erc721", "erc1155", or "specialnft". See the table above for supported categories on each network.'
+ items:
+ type: string
+ enum:
+ - external
+ - internal
+ - erc20
+ - erc721
+ - erc1155
+ - specialnft
+ default: external
+ order:
+ type: string
+ description: |
+ String - Whether to return results in ascending (`asc`) or descending (`desc`) order. Ascending order is from oldest to newest transactions, descending order is from newest to oldest. Defaults to `asc`.
+ enum:
+ - asc
+ - desc
+ withMetadata:
+ type: boolean
+ description: Boolean - Whether or not to include additional metadata about each transfer event. Defaults to `false`.
+ default: false
+ excludeZeroValue:
+ type: boolean
+ description: Boolean - A boolean to exclude transfers with zero value - zero value is not the same as null value. Defaults to `true`.
+ default: true
+ maxCount:
+ type: string
+ description: Max hex string number of results to return per call. Defaults to `0x3e8` (1000).
+ default: '0x3e8'
+ pageKey:
+ type: string
+ description: 'String - UUID for pagination. If more results are available, a uuid pageKey will be returned in the response. Pass that uuid into pageKey to fetch the next 1000 or maxCount.'
+
+
# ============= Debug API Methods ===============
tracer:
type: string
diff --git a/evm_responses.yaml b/evm_responses.yaml
index f06f85d1..045f56f3 100644
--- a/evm_responses.yaml
+++ b/evm_responses.yaml
@@ -158,6 +158,27 @@ log_object:
type: string
description: Hash of the transactions this log was created from. null when its pending log.
+txn_history_log_object:
+ type: object
+ properties:
+ contractAddress:
+ type: string
+ description: 20 Bytes - contract address from which this log originated.
+ logIndex:
+ type: string
+ description: Integer of the log index position in the block. null when its pending log.
+ data:
+ type: string
+ description: Contains one or more 32 Bytes non-indexed arguments of the log.
+ removed:
+ type: boolean
+ description: 'true when the log was removed, due to a chain reorganization. false if its a valid log.'
+ topics:
+ type: array
+ items:
+ type: string
+ description: 'Array of zero to four 32 Bytes DATA of indexed log arguments'
+
block_object:
allOf:
- $ref: '#/nonce_hash_block'
@@ -879,6 +900,39 @@ action_object:
type: string
value:
type: string
+txn_history_trace_object:
+ type: object
+ properties:
+ type:
+ type: string
+ description: CALL or CREATE
+ fromAddress:
+ type: string
+ description: 20 Bytes - address of the sender
+ toAddress:
+ type: string
+ description: 20 Bytes - address of the receiver. null when its a contract creation transaction
+ value:
+ type: string
+ description: amount of value for transfer (in hex)
+ gas:
+ type: string
+ description: amount of gas provided for the call (in hex)
+ gasUsed:
+ type: string
+ description: amount of gas used during the call (in hex)
+ input:
+ type: string
+ description: call data
+ output:
+ type: string
+ description: return data
+ error:
+ type: string
+ description: error, if any
+ revertReason:
+ type: string
+ description: solidity revert reason, if any
trace_filter:
allOf:
- $ref: '#/common_response_fields'
@@ -1257,6 +1311,88 @@ eth_createAccessList:
example:
$ref: ./evm_examples.yaml#/eth_createAccessList
+# ============= Txn History API Methods ===============
+by-address:
+ allOf:
+ - type: object
+ properties:
+ result:
+ type: object
+ description: 'An object with the following fields.'
+ properties:
+ before:
+ type: string
+ description: 'The cursor that points to the previous set of results.'
+ after:
+ type: string
+ description: 'The cursor that points to the end of the current set of results.'
+ totalCount:
+ type: integer
+ description: 'Total count of the response items.'
+ transfers:
+ type: array
+ description: 'Array of objects - sorted in ascending order by time'
+ items:
+ $ref: '#/transaction_history_top_object'
+transaction_history_top_object:
+ type: object
+ properties:
+ network:
+ type: string
+ description: "Network associated with an individual transaction"
+ hash:
+ type: string
+ description: 'Transaction hash'
+ timeStamp:
+ type: string
+ description: '(ISO 8601) Timestamp of transaction mining / confirmation'
+ blockNumber:
+ type: integer
+ description: 'Block number of transaction mining / confirmation'
+ blockHash:
+ type: string
+ description: 'Block hash of transaction mining / confirmation'
+ status:
+ type: string
+ description: '[”confirmed”, “failed”, “removed”]'
+ nonce:
+ type: integer
+ description: 'Transaction nonce'
+ transactionIndex:
+ type: integer
+ description: 'Position of transaction within a block'
+ fromAddress:
+ type: string
+ description: 'From address of transaction (hex string).'
+ toAddress:
+ type: string
+ description: 'To address of transaction (hex string). null if contract creation.'
+ contractAddress:
+ type: string
+ description: '20 Bytes - The contract address created, if the transaction was a contract creation, otherwise null'
+ value:
+ type: string
+ description: "(uint8) Value of native token value moved within the external transaction"
+ cumulativeGasUsed:
+ type: string
+ description: The total amount of gas used when this transaction was executed in the block.
+ effectiveGasPrice:
+ type: string
+ description: Gas price parameter
+ gasUsed:
+ type: string
+ description: The amount of gas used by this specific transaction alone
+ logs:
+ type: array
+ description: 'Array of log objects, which this transaction generated'
+ items:
+ $ref: '#/txn_history_log_object'
+ internalTxns:
+ type: array
+ description: 'Array of internal transaction objects, which this transaction generated'
+ items:
+ $ref: '#/txn_history_trace_object'
+
# ============= Transfers API Methods ===============
alchemy_getAssetTransfers:
allOf:
diff --git a/notify/notify.yaml b/notify/notify.yaml
index 3567b579..f99e5390 100644
--- a/notify/notify.yaml
+++ b/notify/notify.yaml
@@ -14,7 +14,7 @@ paths:
get:
summary: Read Variable Elements
description: |
- This endpoint allows you to read the values within a Custom Webhook variable.
+ This endpoint allows you to read the values within a Custom Webhook variable.
It supports pagination with `limit` and `after` query parameters.
tags: ['Custom Webhook API Methods']
parameters:
diff --git a/transactions/transactions.yaml b/transactions/transactions.yaml
new file mode 100644
index 00000000..7d068e3a
--- /dev/null
+++ b/transactions/transactions.yaml
@@ -0,0 +1,134 @@
+openapi: 3.1.0
+info:
+ title: 📝 Transaction History
+ version: "1.0"
+servers:
+ - url: https://api.g.alchemy.com/data
+x-sandbox:
+ category:
+ type:
+ $ref: '../components/sandbox.yaml#/Category'
+ value: transactions
+paths:
+
+ "/v1/{apiKey}/assets/transactions/by-address":
+ post:
+ summary: Transactions by Address
+ description: The Transaction History API endpoint allows you to query historical transactions for any address, across all chains
+ tags: ["Txn History API Endpoints"]
+ x-readme:
+ samples-languages:
+ - javascript
+ - curl
+ - python
+ - go
+ parameters:
+ - $ref: '#/components/schemas/apiKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TransactionsByAddressRequest"
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: ../evm_responses.yaml#/by-address
+ "400":
+ description: 'Bad Request: Invalid input (e.g., malformed JSON).'
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ "429":
+ description: 'Too Many Requests: Rate limit exceeded.'
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ operationId: by-address
+
+
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ name: Authorization
+ in: header
+ description: An API key that will be supplied in a named header.
+ x-default: Bearer API_KEY
+ schemas:
+ apiKey:
+ name: apiKey
+ in: path
+ schema:
+ type: string
+ default: docs-demo
+ description: |
+
+ For higher throughput, create your own API key
+ required: true
+
+ TransactionsByAddressRequest:
+ type: object
+ properties:
+ after:
+ required: false
+ schema:
+ type: string
+ description: 'The cursor that points to the end of the current set of results.'
+ before:
+ required: false
+ schema:
+ type: string
+ description: 'The cursor that points to the previous set of results.'
+ address:
+ description: Owner wallet address (that can map to a 'from' or 'to' address)
+ example: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+ default: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+ # Vitalik's ETH address
+ network:
+ type: array
+ minItems: 1
+ description:
+ Array of token networks; limited network support while in BETA
+ items:
+ $ref: "#/components/schemas/networkItem"
+ maxItems: 1
+ required:
+ - addresses
+
+ networkItem:
+ type: string
+ example: ETH_MAINNET
+ default: ETH_MAINNET
+ description: |
+
+ Network identifier (e.g., eth-mainnet). Find more network enums here
+ required: true
+
+ ErrorResponse:
+ type: object
+ properties:
+ error:
+ type: object
+ properties:
+ message:
+ type: string
+ description: Detailed error message.
+ required:
+ - message
+ description: Error details.
+ required:
+ - error