forked from stacks-network/stacks-core
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathopenapi.yaml
More file actions
2322 lines (2233 loc) · 78.8 KB
/
openapi.yaml
File metadata and controls
2322 lines (2233 loc) · 78.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.1.0
servers:
- url: http://localhost:20443
description: Local Stacks Node
info:
title: Stacks 3.0+ RPC API
version: "1.0.0"
description: |
This is the documentation for the `stacks-node` RPC interface.
license:
name: CC-0
url: https://creativecommons.org/publicdomain/zero/1.0/
tags:
- name: Transactions
description: Operations related to broadcasting and retrieving transactions.
- name: Smart Contracts
description: Endpoints for interacting with Clarity smart contracts.
- name: Accounts
description: Endpoints for retrieving account information.
- name: Fees
description: Endpoints for fee estimation.
- name: Info
description: General informational endpoints about the node.
- name: Mining
description: Endpoints related to Stacks block production and mining.
- name: Blocks
description: Operations for retrieving block and microblock data.
- name: Signers
description: Endpoints for retrieving signer information.
- name: Atlas
description: Operations related to the Atlas global namespace.
- name: Microblocks
description: Operations for retrieving and submitting microblocks.
- name: StackerDB
description: Endpoints for interacting with StackerDB instances.
components:
securitySchemes:
rpcAuth:
type: apiKey
in: header
name: authorization
description: |
Plain-text secret value that must exactly equal the node's
configured password, which is set as `connection_options.auth_token`
in the node's configuration file.
responses:
Unauthorized:
description: Unauthorized. Invalid or missing authentication token.
content:
text/plain:
schema:
type: string
example: "Unauthorized"
BadRequest:
description: Bad request
content:
text/plain:
schema:
type: string
example: "Bad request"
NotFound:
description: Not found
content:
text/plain:
schema:
type: string
example: "Not found"
InternalServerError:
description: Internal Server Error
content:
text/plain:
schema:
type: string
example: "Internal Server Error"
Timeout:
description: Timeout
content:
text/plain:
schema:
type: string
example: "Timeout"
schemas:
NodeInfo:
$ref: ./components/schemas/node-info.schema.yaml
PoxInfo:
$ref: ./components/schemas/pox-info.schema.yaml
Sortitions:
$ref: ./components/schemas/sortitions.schema.yaml
GetHealth:
$ref: ./components/schemas/get-health.schema.yaml
AccountData:
$ref: ./components/schemas/account-data.schema.yaml
# Transaction Schemas
TransactionSubmissionError:
$ref: ./components/schemas/transaction-submission-error.schema.yaml
FeeTransactionRequest:
$ref: ./components/schemas/fee-transaction-request.schema.yaml
FeeTransactionResponse:
$ref: ./components/schemas/fee-transaction-response.schema.yaml
FeeTransactionError:
$ref: ./components/schemas/fee-transaction-error.schema.yaml
# Contract & Clarity Schemas
ContractInterface:
$ref: ./components/schemas/contract-interface.schema.yaml
ContractSource:
$ref: ./components/schemas/contract-source.schema.yaml
ReadOnlyFunctionArgs:
$ref: ./components/schemas/read-only-function-args.schema.yaml
ReadOnlyFunctionResult:
$ref: ./components/schemas/read-only-function-result.schema.yaml
ClarityName:
$ref: ./components/schemas/clarity-name.schema.yaml
ClarityMetadata:
$ref: ./components/schemas/clarity-metadata.schema.yaml
ConstantValue:
$ref: ./components/schemas/constant-value.schema.yaml
IsTraitImplemented:
$ref: ./components/schemas/is-trait-implemented.schema.yaml
# Other Schemas
SignerBlocksSigned:
$ref: ./components/schemas/signer-blocks-signed.schema.yaml
UnconfirmedTransaction:
$ref: ./components/schemas/unconfirmed-transaction.schema.yaml
BlockUploadResponse:
$ref: ./components/schemas/block-upload-response.schema.yaml
AttachmentInventory:
$ref: ./components/schemas/attachment-inventory.schema.yaml
AttachmentData:
$ref: ./components/schemas/attachment-data.schema.yaml
StackerDbMetadata:
$ref: ./components/schemas/stackerdb-metadata.schema.yaml
StackerDbReplicas:
$ref: ./components/schemas/stackerdb-replicas.schema.yaml
StackerDbChunkData:
$ref: ./components/schemas/stackerdb-chunk-data.schema.yaml
StackerDbChunkAckData:
$ref: ./components/schemas/stackerdb-chunk-ack-data.schema.yaml
ClarityData:
$ref: ./components/schemas/clarity-data.schema.yaml
BlockHeaders:
$ref: ./components/schemas/block-headers.schema.yaml
BlockProposalResponse:
$ref: ./components/schemas/block-proposal.schema.yaml
NetworkPeers:
$ref: ./components/schemas/network-peers.schema.yaml
TransactionInfo:
$ref: ./components/schemas/get-transaction.schema.yaml
TenureForkInfo:
$ref: ./components/schemas/tenure-fork-info.schema.yaml
TenureInfo:
$ref: ./components/schemas/tenure-info.schema.yaml
TenureTip:
$ref: ./components/schemas/tenure-tip.schema.yaml
TenureTipMetadata:
$ref: ./components/schemas/tenure-tip-metadata.schema.yaml
GetStackerSet:
$ref: ./components/schemas/get-stacker-set.schema.yaml
TenureBlocks:
$ref: ./components/schemas/tenure-blocks.schema.yaml
BlockReplay:
$ref: ./components/schemas/block-replay.schema.yaml
paths:
/v2/transactions:
post:
summary: Broadcast raw transaction
tags:
- Transactions
security: []
description: |
Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js)
project to generate a raw transaction payload.
The node performs static validation checks on transactions before accepting them into the mempool, including:
- Transaction format validation
- Signature verification
- Nonce checking
- Fee validation
- Size limits
operationId: broadcastTransaction
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
example: binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000
application/json:
schema:
type: object
required: ["tx"]
properties:
tx:
type: string
pattern: "^[0-9a-f]+$"
description: Hex-encoded transaction
attachment:
type: string
pattern: "^[0-9a-f]+$"
description: Optional hex-encoded attachment for contract-call transactions
example:
tx: "00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000"
attachment: "68656c6c6f20776f726c64"
responses:
"200":
description: Transaction ID of successful post of a raw tx to the node's mempool.
content:
application/json:
schema:
type: string
pattern: "^[0-9a-f]{64}$"
example: "e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionSubmissionError"
examples:
transaction-submission-error:
$ref: "./components/examples/transaction-submission-error.example.json"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/contracts/interface/{contract_address}/{contract_name}:
get:
summary: Get contract interface
description: Get contract interface using a `contract_address` and `contract name`
tags:
- Smart Contracts
security: []
operationId: getContractInterface
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- $ref: ./components/parameters/tip.yaml
responses:
"200":
description: Contract interface
content:
application/json:
schema:
$ref: "#/components/schemas/ContractInterface"
examples:
contract-interface:
$ref: "./components/examples/contract-interface.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/map_entry/{contract_address}/{contract_name}/{map_name}:
post:
summary: Get specific data-map inside a contract
tags:
- Smart Contracts
security: []
operationId: getContractDataMapEntry
description: |
Attempt to fetch data from a contract data map. The contract is
identified with [Stacks Address] and [Contract Name] in the URL path.
The map is identified with [Map Name].
The key to lookup in the map is supplied via the POST body. This should
be supplied as the hex string serialization of the key (which should be
a Clarity value). Note, this is a JSON string.
The response is a JSON object with the following properties:
- `data`: The hex serialization of the map response. Note that map
responses are Clarity option types, for non-existent values, this is
a serialized none, and for all other responses, it is a serialized
(some ...) object.
- `proof`: The hex serialization of the Merkle proof for the data.
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: map_name
in: path
required: true
schema:
$ref: "#/components/schemas/ClarityName"
- $ref: ./components/parameters/proof.yaml
- $ref: ./components/parameters/tip.yaml
x-codegen-request-body-name: key
requestBody:
description: Hex string serialization of the lookup key (which should be a Clarity value)
required: true
content:
application/json:
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ClarityData"
examples:
clarity-data:
$ref: "./components/examples/clarity-data.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/contracts/source/{contract_address}/{contract_name}:
get:
summary: Get contract source
tags:
- Smart Contracts
security: []
operationId: getContractSource
description: |
Returns the Clarity source code of a given contract, along with the
block height it was published in, and the MARF proof for the data.
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- $ref: ./components/parameters/proof.yaml
- $ref: ./components/parameters/tip.yaml
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ContractSource"
examples:
contract-source:
$ref: "./components/examples/contract-source.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}:
post:
summary: Call read-only function
description: |
Call a read-only public function on a given contract.
The contract is identified with [Stacks Address] and [Contract Name] in the URL path.
The function is identified with [Function Name].
The arguments to the function are supplied via the POST body.
This should be a JSON object with two main properties:
- `sender` which should be a standard Stacks address
- `arguments` which should be an array of hex-encoded Clarity values.
tags:
- Smart Contracts
security: []
operationId: callReadOnlyFunction
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: function_name
in: path
required: true
schema:
$ref: "#/components/schemas/ClarityName"
- $ref: ./components/parameters/tip.yaml
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReadOnlyFunctionArgs"
responses:
"200":
description: Function executed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/ReadOnlyFunctionResult"
examples:
success:
$ref: "./components/examples/read-only-function-success.example.json"
failure:
$ref: "./components/examples/read-only-function-failure.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
/v3/contracts/fast-call-read/{contract_address}/{contract_name}/{function_name}:
post:
summary: Call read-only function in fast mode (no cost and memory tracking)
description: |
Call a read-only public function on a given smart contract without cost tracking.
The contract is identified with [Stacks Address] and [Contract Name] in the URL path.
The function is identified with [Function Name].
The arguments to the function are supplied via the POST body.
This should be a JSON object with two main properties:
- `sender` which should be a standard Stacks address
- `arguments` which should be an array of hex-encoded Clarity values.
**This API endpoint requires a basic Authorization header.**
tags:
- Smart Contracts
security:
- rpcAuth: []
operationId: fastCallReadOnlyFunction
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: function_name
in: path
required: true
schema:
$ref: "#/components/schemas/ClarityName"
- $ref: ./components/parameters/tip.yaml
requestBody:
description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReadOnlyFunctionArgs"
examples:
fast-call-request:
summary: Fast call read-only function request
value:
sender: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info"
arguments:
- "0x0011..."
- "0x00231..."
responses:
"200":
description: Function executed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/ReadOnlyFunctionResult"
examples:
success:
$ref: "./components/examples/read-only-function-success.example.json"
failure:
$ref: "./components/examples/read-only-function-failure.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"408":
$ref: "#/components/responses/Timeout"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/accounts/{principal}:
get:
summary: Get account info
tags:
- Accounts
security: []
operationId: getAccountInfo
description: |
Get the account data for the provided principal
Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is a unsigned 64-bit integer, and the proofs are provided as hex strings.
For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.
parameters:
- $ref: ./components/parameters/principal.yaml
- $ref: ./components/parameters/proof.yaml
- $ref: ./components/parameters/tip.yaml
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/AccountData"
examples:
account-data:
$ref: "./components/examples/account-data.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/fees/transaction:
post:
summary: Get approximate fees for the given transaction
tags:
- Fees
security: []
description: |
Get an estimated fee for the supplied transaction. This
estimates the execution cost of the transaction, the current
fee rate of the network, and returns estimates for fee
amounts.
* `transaction_payload` is a hex-encoded serialization of
the TransactionPayload for the transaction.
* `estimated_len` is an optional argument that provides the
endpoint with an estimation of the final length (in bytes)
of the transaction, including any post-conditions and
signatures
If the node cannot provide an estimate for the transaction
(e.g., if the node has never seen a contract-call for the
given contract and function) or if estimation is not
configured on this node, a 400 response is returned.
The 400 response will be a JSON error containing a `reason`
field which can be one of the following:
* `DatabaseError` - this Stacks node has had an internal
database error while trying to estimate the costs of the
supplied transaction.
* `NoEstimateAvailable` - this Stacks node has not seen this
kind of contract-call before, and it cannot provide an
estimate yet.
* `CostEstimationDisabled` - this Stacks node does not perform
fee or cost estimation, and it cannot respond on this
endpoint.
The 200 response contains the following data:
* `estimated_cost` - the estimated multi-dimensional cost of
executing the Clarity VM on the provided transaction.
* `estimated_cost_scalar` - a unitless integer that the Stacks
node uses to compare how much of the block limit is consumed
by different transactions. This value incorporates the
estimated length of the transaction and the estimated
execution cost of the transaction. The range of this integer
may vary between different Stacks nodes. In order to compute
an estimate of total fee amount for the transaction, this
value is multiplied by the same Stacks node"s estimated fee
rate.
* `cost_scalar_change_by_byte` - a float value that indicates how
much the `estimated_cost_scalar` value would increase for every
additional byte in the final transaction.
* `estimations` - an array of estimated fee rates and total fees to
pay in microSTX for the transaction. This array provides a range of
estimates (default: 3) that may be used. Each element of the array
contains the following fields:
* `fee_rate` - the estimated value for the current fee
rates in the network
* `fee` - the estimated value for the total fee in
microSTX that the given transaction should pay. These
values are the result of computing:
`fee_rate` x `estimated_cost_scalar`.
If the estimated fees are less than the minimum relay
fee `(1 ustx x estimated_len)`, then that minimum relay
fee will be returned here instead.
Note: If the final transaction"s byte size is larger than
supplied to `estimated_len`, then applications should increase
this fee amount by:
`fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`)
operationId: getFeeTransaction
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/FeeTransactionRequest"
examples:
fee-transaction-request:
$ref: "./components/examples/fee-transaction-request.example.json"
responses:
"200":
description: Estimated fees for the transaction
content:
application/json:
schema:
$ref: "#/components/schemas/FeeTransactionResponse"
examples:
fee-transaction-response:
$ref: "./components/examples/fee-transaction-response.example.json"
"400":
description: Fee estimation error
content:
application/json:
schema:
$ref: "#/components/schemas/FeeTransactionError"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/fees/transfer:
get:
summary: Get estimated fee
tags:
- Fees
security: []
operationId: getFeeTransfer
description: |
Get an estimated fee rate for STX transfer transactions. This is a fee
rate per byte, returned as a JSON integer (microSTX per byte).
responses:
"200":
description: Fee rate in microSTX per byte
content:
application/json:
schema:
type: integer
minimum: 1
description: Fee rate in microSTX per byte
example: 3
"500":
$ref: "#/components/responses/InternalServerError"
/v2/info:
get:
summary: Get Core API info
description: Get Core API information
tags:
- Info
security: []
operationId: getNodeInfo
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/NodeInfo"
examples:
node-info:
$ref: "./components/examples/node-info.example.json"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/pox:
get:
summary: Get PoX details
description: Get Proof of Transfer (PoX) information. Can be used for Stacking.
tags:
- Info
security: []
operationId: getPoxInfo
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/PoxInfo"
examples:
pox-info:
$ref: "./components/examples/pox-info.example.json"
parameters:
- $ref: ./components/parameters/tip.yaml
/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}:
get:
summary: Get trait implementation details
description: |
Determine whether or not a specified trait is implemented (either
explicitly or implicitly) within a given contract.
tags:
- Smart Contracts
security: []
operationId: checkTraitImplementation
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: trait_contract_address
in: path
required: true
description: |
Stacks address of the trait-defining contract.
schema:
type: string
pattern: "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$"
minLength: 28
maxLength: 41
example: "SP2Z1K16238380NBP4T38A4G10A90Q03JJ2C2003"
- name: trait_contract_name
in: path
required: true
description: Contract name of the trait-defining contract.
schema:
type: string
pattern: "^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$"
minLength: 1
maxLength: 128
example: "some-trait"
- name: trait_name
in: path
required: true
schema:
$ref: "#/components/schemas/ClarityName"
example: "some-trait"
- $ref: ./components/parameters/tip.yaml
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/IsTraitImplemented"
examples:
is-trait-implemented:
$ref: "./components/examples/is-trait-implemented.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
/v2/clarity/marf/{marf_key_hash}:
get:
summary: Get the MARF value for a given key
tags:
- Smart Contracts
security: []
operationId: getClarityMarfValue
description: |
Attempt to fetch the value of a MARF key. The key is a 64-character
hex string representing the MARF node hash.
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ClarityData"
examples:
clarity-data:
$ref: "./components/examples/clarity-data.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
parameters:
- name: marf_key_hash
in: path
required: true
description: The 64-character hex-encoded hash of the MARF key.
schema:
type: string
pattern: "^[0-9a-f]{64}$"
minLength: 64
maxLength: 64
- $ref: ./components/parameters/proof.yaml
- $ref: ./components/parameters/tip.yaml
/v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key}:
get:
summary: Get the contract metadata for the metadata key
tags:
- Smart Contracts
security: []
operationId: getClarityMetadata
description: |
Attempt to fetch the metadata of a contract. The contract is identified
with [Contract Address] and [Contract Name] in the URL path. The metadata
key is identified with [Clarity Metadata Key].
In the response, `data` is formatted as JSON.
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ClarityMetadata"
examples:
clarity-metadata:
$ref: "./components/examples/clarity-metadata.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: clarity_metadata_key
in: path
required: true
description: Metadata key
schema:
type: string
- $ref: ./components/parameters/tip.yaml
/v2/constant_val/{contract_address}/{contract_name}/{constant_name}:
get:
summary: Get the value of a constant inside a contract
tags:
- Smart Contracts
security: []
operationId: getConstantValue
description: |
Attempt to fetch the value of a constant inside a contract. The contract
is identified with [Stacks Address] and [Contract Name] in the URL path.
The constant is identified with [Constant Name].
In the response, `data` is the hex serialization of the constant value.
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ConstantValue"
examples:
constant-value:
$ref: "./components/examples/constant-value.example.json"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
parameters:
- $ref: ./components/parameters/contract-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: constant_name
in: path
required: true
schema:
$ref: "#/components/schemas/ClarityName"
- $ref: ./components/parameters/tip.yaml
/v3/block_proposal:
post:
summary: Validate a proposed Stacks block
tags:
- Mining
operationId: postBlockProposal
description: |
Used by stackers to validate a proposed Stacks block from a miner.
**This API endpoint requires a basic Authorization header.**
security:
- rpcAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: ["block", "chain_id"]
properties:
block:
type: string
description: Hex-encoded block data
chain_id:
type: integer
description: Chain ID for the block
examples:
block-proposal-request:
$ref: "./components/examples/post-block-proposal-request.example.json"
responses:
"202":
description: |
Block proposal has been accepted for processing.
The result will be returned via the event observer.
content:
application/json:
schema:
$ref: "#/components/schemas/BlockProposalResponse"
examples:
block-proposal-accepted:
$ref: "./components/examples/post-block-proposal-response.example.json"
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/BlockProposalResponse"
example:
result: "Error"
message: "Bad Request."
text/plain:
schema:
type: string
example: "Bad request."
"401":
$ref: "#/components/responses/Unauthorized"
"429":
description: |
There is an ongoing proposal validation being processed, the new
request cannot be accepted until the prior request has been processed.
content:
application/json:
schema:
$ref: "#/components/schemas/BlockProposalResponse"
examples:
too-many-requests:
$ref: "./components/examples/post-block-proposal-response.429.example.json"
"500":
$ref: "#/components/responses/InternalServerError"
/v3/stacker_set/{cycle_number}:
get:
summary: Fetch the stacker and signer set information for a given cycle.
tags:
- Signers
security: []
operationId: getStackerSet
description: |
Used to get stacker and signer set information for a given cycle.
This will only return information for cycles started in Epoch-2.5
where PoX-4 was active and subsequent cycles.
parameters:
- name: cycle_number
in: path
required: true
description: reward cycle number
schema:
type: integer
- $ref: ./components/parameters/tip.yaml
responses:
"200":
description: Information for the given reward cycle
content:
application/json:
schema:
$ref: "#/components/schemas/GetStackerSet"
examples:
stacker-set:
$ref: "./components/examples/get-stacker-set.example.json"
"400":
description: Could not fetch the given reward set
content:
application/json:
schema:
type: object
required:
- response
- err_msg
properties:
response:
type: string
enum: ["error"]
description: Response status
err_type:
type: string
description: Error type classification
err_msg:
type: string
description: Detailed error message
examples:
stacker-set-error:
$ref: "./components/examples/get-stacker-set-400.example.json"
/v3/blocks/{block_id}:
get:
summary: Get Nakamoto block by ID
tags:
- Blocks
security: []
operationId: getNakamotoBlockById
description: |
Get a specific Nakamoto block (Stacks 3.x+) by its index block hash. This endpoint streams
the block data from the Nakamoto staging blocks database where Nakamoto blocks are stored
with additional metadata including tenure information.
**Compatibility**: Works with Nakamoto blocks only. For Stacks 2.x blocks, use `/v2/blocks/{block_id}`.
parameters:
- name: block_id
in: path
description: The block"s ID hash
required: true
schema:
type: string
responses:
"200":
description: The raw SIP-003-encoded block will be returned.
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/InternalServerError"
/v3/blocks/height/{block_height}:
get:
summary: Fetch a Nakamoto block by its height and optional tip
tags: