Skip to content

Commit d0e7ff4

Browse files
pileofscrapspileofscraps
committed
added in txn history API spec
1 parent f2e484e commit d0e7ff4

File tree

5 files changed

+352
-1
lines changed

5 files changed

+352
-1
lines changed

‎components/sandbox.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ Category:
1515
- private-transactions
1616
- notify
1717
- transaction-simulation
18+
- transactions
1819
# - accounts

‎evm_body.yaml

+80
Original file line numberDiff line numberDiff line change
@@ -1355,6 +1355,86 @@ alchemy_getAssetTransfers:
13551355
type: string
13561356
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.'
13571357

1358+
# ============= Txn History API Methods ===============
1359+
by-address:
1360+
allOf:
1361+
- $ref: '#/common_request_fields'
1362+
- type: object
1363+
properties:
1364+
method:
1365+
$ref: ./components/schemas.yaml#/Method
1366+
default: by-address
1367+
params:
1368+
type: array
1369+
minItems: 1
1370+
maxItems: 1
1371+
items:
1372+
type: object
1373+
required:
1374+
- category
1375+
properties:
1376+
fromBlock:
1377+
type: string
1378+
description: 'String - Inclusive from block (hex string, int, `latest`, or `indexed`). Defaults to `0x0`'
1379+
default: '0x0'
1380+
toBlock:
1381+
type: string
1382+
description: 'String - Inclusive to block (hex string, int, `latest`, or `indexed`). Defaults to `latest`. Read more about block tags <span class="custom-style"><a href="https://docs.alchemy.com/reference/transfers-api-quickstart#what-are-the-different-types-of-block-tags" target="_blank">here</a></span>'
1383+
default: latest
1384+
fromAddress:
1385+
type: string
1386+
description: String - From address (hex string). Default wildcard - any address
1387+
pattern: '^0[xX][0-9a-fA-F]+$'
1388+
toAddress:
1389+
type: string
1390+
description: String - To address (hex string). Default wildcard - any address
1391+
pattern: '^0[xX][0-9a-fA-F]+$'
1392+
default: '0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1'
1393+
contractAddresses:
1394+
type: array
1395+
description: 'String - List of contract addresses (hex strings) to filter for - only applies to "erc20", "erc721", "erc1155" transfers. Default wildcard - any address'
1396+
items:
1397+
type: string
1398+
pattern: '^0[xX][0-9a-fA-F]+$'
1399+
category:
1400+
type: array
1401+
minItems: 1
1402+
description: |
1403+
'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.'
1404+
items:
1405+
type: string
1406+
enum:
1407+
- external
1408+
- internal
1409+
- erc20
1410+
- erc721
1411+
- erc1155
1412+
- specialnft
1413+
default: external
1414+
order:
1415+
type: string
1416+
description: |
1417+
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`.
1418+
enum:
1419+
- asc
1420+
- desc
1421+
withMetadata:
1422+
type: boolean
1423+
description: Boolean - Whether or not to include additional metadata about each transfer event. Defaults to `false`.
1424+
default: false
1425+
excludeZeroValue:
1426+
type: boolean
1427+
description: Boolean - A boolean to exclude transfers with zero value - zero value is not the same as null value. Defaults to `true`.
1428+
default: true
1429+
maxCount:
1430+
type: string
1431+
description: Max hex string number of results to return per call. Defaults to `0x3e8` (1000).
1432+
default: '0x3e8'
1433+
pageKey:
1434+
type: string
1435+
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.'
1436+
1437+
13581438
# ============= Debug API Methods ===============
13591439
tracer:
13601440
type: string

‎evm_responses.yaml

+136
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,27 @@ log_object:
158158
type: string
159159
description: Hash of the transactions this log was created from. null when its pending log.
160160

161+
txn_history_log_object:
162+
type: object
163+
properties:
164+
contractAddress:
165+
type: string
166+
description: 20 Bytes - contract address from which this log originated.
167+
logIndex:
168+
type: string
169+
description: Integer of the log index position in the block. null when its pending log.
170+
data:
171+
type: string
172+
description: Contains one or more 32 Bytes non-indexed arguments of the log.
173+
removed:
174+
type: boolean
175+
description: 'true when the log was removed, due to a chain reorganization. false if its a valid log.'
176+
topics:
177+
type: array
178+
items:
179+
type: string
180+
description: 'Array of zero to four 32 Bytes DATA of indexed log arguments'
181+
161182
block_object:
162183
allOf:
163184
- $ref: '#/nonce_hash_block'
@@ -879,6 +900,39 @@ action_object:
879900
type: string
880901
value:
881902
type: string
903+
txn_history_trace_object:
904+
type: object
905+
properties:
906+
type:
907+
type: string
908+
description: CALL or CREATE
909+
fromAddress:
910+
type: string
911+
description: 20 Bytes - address of the sender
912+
toAddress:
913+
type: string
914+
description: 20 Bytes - address of the receiver. null when its a contract creation transaction
915+
value:
916+
type: string
917+
description: amount of value for transfer (in hex)
918+
gas:
919+
type: string
920+
description: amount of gas provided for the call (in hex)
921+
gasUsed:
922+
type: string
923+
description: amount of gas used during the call (in hex)
924+
input:
925+
type: string
926+
description: call data
927+
output:
928+
type: string
929+
description: return data
930+
error:
931+
type: string
932+
description: error, if any
933+
revertReason:
934+
type: string
935+
description: solidity revert reason, if any
882936
trace_filter:
883937
allOf:
884938
- $ref: '#/common_response_fields'
@@ -1257,6 +1311,88 @@ eth_createAccessList:
12571311
example:
12581312
$ref: ./evm_examples.yaml#/eth_createAccessList
12591313

1314+
# ============= Txn History API Methods ===============
1315+
by-address:
1316+
allOf:
1317+
- type: object
1318+
properties:
1319+
result:
1320+
type: object
1321+
description: 'An object with the following fields.'
1322+
properties:
1323+
before:
1324+
type: string
1325+
description: 'The cursor that points to the previous set of results.'
1326+
after:
1327+
type: string
1328+
description: 'The cursor that points to the end of the current set of results.'
1329+
totalCount:
1330+
type: integer
1331+
description: 'Total count of the response items.'
1332+
transfers:
1333+
type: array
1334+
description: 'Array of objects - sorted in ascending order by time'
1335+
items:
1336+
$ref: '#/transaction_history_top_object'
1337+
transaction_history_top_object:
1338+
type: object
1339+
properties:
1340+
network:
1341+
type: string
1342+
description: "Network associated with an individual transaction"
1343+
hash:
1344+
type: string
1345+
description: 'Transaction hash'
1346+
timeStamp:
1347+
type: string
1348+
description: '(ISO 8601) Timestamp of transaction mining / confirmation'
1349+
blockNumber:
1350+
type: integer
1351+
description: 'Block number of transaction mining / confirmation'
1352+
blockHash:
1353+
type: string
1354+
description: 'Block hash of transaction mining / confirmation'
1355+
status:
1356+
type: string
1357+
description: '[”confirmed”, “failed”, “removed”]'
1358+
nonce:
1359+
type: integer
1360+
description: 'Transaction nonce'
1361+
transactionIndex:
1362+
type: integer
1363+
description: 'Position of transaction within a block'
1364+
fromAddress:
1365+
type: string
1366+
description: 'From address of transaction (hex string).'
1367+
toAddress:
1368+
type: string
1369+
description: 'To address of transaction (hex string). null if contract creation.'
1370+
contractAddress:
1371+
type: string
1372+
description: '20 Bytes - The contract address created, if the transaction was a contract creation, otherwise null'
1373+
value:
1374+
type: string
1375+
description: "(uint8) Value of native token value moved within the external transaction"
1376+
cumulativeGasUsed:
1377+
type: string
1378+
description: The total amount of gas used when this transaction was executed in the block.
1379+
effectiveGasPrice:
1380+
type: string
1381+
description: Gas price parameter
1382+
gasUsed:
1383+
type: string
1384+
description: The amount of gas used by this specific transaction alone
1385+
logs:
1386+
type: array
1387+
description: 'Array of log objects, which this transaction generated'
1388+
items:
1389+
$ref: '#/txn_history_log_object'
1390+
internalTxns:
1391+
type: array
1392+
description: 'Array of internal transaction objects, which this transaction generated'
1393+
items:
1394+
$ref: '#/txn_history_trace_object'
1395+
12601396
# ============= Transfers API Methods ===============
12611397
alchemy_getAssetTransfers:
12621398
allOf:

‎notify/notify.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ paths:
1414
get:
1515
summary: Read Variable Elements
1616
description: |
17-
This endpoint allows you to read the values within a Custom Webhook variable.
17+
This endpoint allows you to read the values within a Custom Webhook variable.
1818
It supports pagination with `limit` and `after` query parameters.
1919
tags: ['Custom Webhook API Methods']
2020
parameters:

‎transactions/transactions.yaml

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
openapi: 3.1.0
2+
info:
3+
title: 📝 Transaction History
4+
version: "1.0"
5+
servers:
6+
- url: https://api.g.alchemy.com/data
7+
x-sandbox:
8+
category:
9+
type:
10+
$ref: '../components/sandbox.yaml#/Category'
11+
value: transactions
12+
paths:
13+
14+
"/v1/{apiKey}/assets/transactions/by-address":
15+
post:
16+
summary: Transactions by Address
17+
description: The Transaction History API endpoint allows you to query historical transactions for any address, across all chains
18+
tags: ["Txn History API Endpoints"]
19+
x-readme:
20+
samples-languages:
21+
- javascript
22+
- curl
23+
- python
24+
- go
25+
parameters:
26+
- $ref: '#/components/schemas/apiKey'
27+
requestBody:
28+
required: true
29+
content:
30+
application/json:
31+
schema:
32+
$ref: "#/components/schemas/TransactionsByAddressRequest"
33+
responses:
34+
'200':
35+
description: ''
36+
content:
37+
application/json:
38+
schema:
39+
$ref: ../evm_responses.yaml#/by-address
40+
"400":
41+
description: 'Bad Request: Invalid input (e.g., malformed JSON).'
42+
content:
43+
application/json:
44+
schema:
45+
$ref: "#/components/schemas/ErrorResponse"
46+
"429":
47+
description: 'Too Many Requests: Rate limit exceeded.'
48+
content:
49+
application/json:
50+
schema:
51+
$ref: "#/components/schemas/ErrorResponse"
52+
operationId: by-address
53+
54+
55+
components:
56+
securitySchemes:
57+
apiKey:
58+
type: apiKey
59+
name: Authorization
60+
in: header
61+
description: An API key that will be supplied in a named header.
62+
x-default: Bearer API_KEY
63+
schemas:
64+
apiKey:
65+
name: apiKey
66+
in: path
67+
schema:
68+
type: string
69+
default: docs-demo
70+
description: |
71+
<style>
72+
.custom-style {
73+
color: #048FF4;
74+
}
75+
</style>
76+
For higher throughput, <span class="custom-style"><a href="https://alchemy.com/?a=docs-demo" target="_blank">create your own API key</a></span>
77+
required: true
78+
79+
TransactionsByAddressRequest:
80+
type: object
81+
properties:
82+
after:
83+
required: false
84+
schema:
85+
type: string
86+
description: 'The cursor that points to the end of the current set of results.'
87+
before:
88+
required: false
89+
schema:
90+
type: string
91+
description: 'The cursor that points to the previous set of results.'
92+
address:
93+
description: Owner wallet address (that can map to a 'from' or 'to' address)
94+
example: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
95+
default: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
96+
# Vitalik's ETH address
97+
network:
98+
type: array
99+
minItems: 1
100+
description:
101+
Array of token networks; limited network support while in BETA
102+
items:
103+
$ref: "#/components/schemas/networkItem"
104+
maxItems: 1
105+
required:
106+
- addresses
107+
108+
networkItem:
109+
type: string
110+
example: ETH_MAINNET
111+
default: ETH_MAINNET
112+
description: |
113+
<style>
114+
.custom-style {
115+
color: #048FF4;
116+
}
117+
</style>
118+
Network identifier (e.g., eth-mainnet). Find more network enums <span class="custom-style"><a href="https://dashboard.alchemy.com/chains" target="_blank">here</a></span>
119+
required: true
120+
121+
ErrorResponse:
122+
type: object
123+
properties:
124+
error:
125+
type: object
126+
properties:
127+
message:
128+
type: string
129+
description: Detailed error message.
130+
required:
131+
- message
132+
description: Error details.
133+
required:
134+
- error

0 commit comments

Comments
 (0)