Hiro Faucets API
Endpoints to request STX or BTC tokens (not possible on Mainnet)
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts Faucets API
description: Welcome to the API reference overview for the Signer Metrics API.
version: 1.0.3
servers:
- url: https://api.hiro.so/
description: mainnet
- url: https://api.testnet.hiro.so/
description: testnet
tags:
- name: Faucets
description: Endpoints to request STX or BTC tokens (not possible on Mainnet)
paths:
/extended/v1/faucets/btc:
post:
operationId: run_faucet_btc
summary: Add regtest BTC tokens to address
tags:
- Faucets
description: "Add 0.01 BTC token to the specified regtest BTC address.\n\n The endpoint returns the transaction ID, which you can use to view the transaction in a regtest Bitcoin block\n explorer. The tokens are delivered once the transaction has been included in a block.\n\n **Note:** This is a Bitcoin regtest-only endpoint. This endpoint will not work on the Bitcoin mainnet."
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
properties:
address:
description: A valid regtest BTC address
examples:
- 2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts
type: string
- type: 'null'
parameters:
- schema:
type: string
example: 2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts
in: query
name: address
required: false
description: A valid regtest BTC address
- schema:
default: false
type: boolean
in: query
name: large
required: false
description: Request a large amount of regtest BTC than the default
- schema:
default: false
type: boolean
in: query
name: xlarge
required: false
description: Request an extra large amount of regtest BTC than the default
responses:
'200':
description: POST request that initiates a transfer of tokens to a specified Bitcoin regtest address
content:
application/json:
schema:
title: RunFaucetResponse
description: POST request that initiates a transfer of tokens to a specified Bitcoin regtest address
type: object
properties:
success:
description: Indicates if the faucet call was successful
type: boolean
enum:
- true
txid:
description: The transaction ID for the faucet call
type: string
raw_tx:
description: Raw transaction in hex string representation
type: string
required:
- success
- txid
- raw_tx
4XX:
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
error:
description: Error message
type: string
required:
- success
- error
/extended/v1/faucets/btc/{address}:
get:
operationId: get_btc_balance
summary: Get BTC balance for address
tags:
- Faucets
parameters:
- schema:
type: string
example: 2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts
in: path
name: address
required: true
description: A valid regtest BTC address
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
balance:
description: Address balance in BTC
type: number
required:
- balance
4XX:
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
error:
description: Error message
type: string
required:
- success
- error
/extended/v1/faucets/stx:
post:
operationId: run_faucet_stx
summary: Get STX testnet tokens
tags:
- Faucets
description: "Add 500 STX tokens to the specified testnet address. Testnet STX addresses begin with `ST`. If the `stacking`\n parameter is set to `true`, the faucet will add the required number of tokens for individual stacking to the\n specified testnet address.\n\n The endpoint returns the transaction ID, which you can use to view the transaction in the\n [Stacks Explorer](https://explorer.hiro.so/?chain=testnet). The tokens are delivered once the transaction has\n been included in an anchor block.\n\n A common reason for failed faucet transactions is that the faucet has run out of tokens. If you are experiencing\n failed faucet transactions to a testnet address, you can get help in [Discord](https://stacks.chat).\n\n **Note:** This is a testnet only endpoint. This endpoint will not work on the mainnet."
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
properties:
address:
description: '[Deprecated -- use query param rather than POST body] A valid testnet STX address'
examples:
- ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ
type: string
- type: 'null'
parameters:
- schema:
type: string
example: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ
in: query
name: address
required: false
description: A valid testnet STX address
- schema:
default: false
type: boolean
in: query
name: stacking
required: false
description: Request the amount of STX tokens needed for individual address stacking
responses:
'200':
description: POST request that initiates a transfer of tokens to a specified testnet address
content:
application/json:
schema:
title: RunFaucetResponse
description: POST request that initiates a transfer of tokens to a specified testnet address
type: object
properties:
success:
description: Indicates if the faucet call was successful
type: boolean
enum:
- true
txId:
description: The transaction ID for the faucet call
type: string
txRaw:
description: Raw transaction in hex string representation
type: string
required:
- success
- txId
- txRaw
4XX:
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
description: Indicates if the faucet call was successful
type: boolean
enum:
- false
error:
description: Error message
type: string
help:
type: string
required:
- success
- error
externalDocs:
url: https://github.com/hirosystems/signer-metrics-api
description: Source Repository