v1


Paths

GET /health

Returns OK if healthy.

GET /health

Responses

HTTP Code Description Schema
200 OK. No Content
default Unknown Error No Content

Produces

  • application/json

GET /metrics

Return metrics about algod functioning.

GET /metrics

Responses

HTTP Code Description Schema
200 text with #-comments and key:value lines No Content
404 metrics were compiled out No Content

Produces

  • text/plain

GET /swagger.json

Gets the current swagger spec.

GET /swagger.json

Description Returns the entire swagger spec in json.

Responses

HTTP Code Description Schema
200 The current swagger spec string
default Unknown Error No Content

Produces

  • application/json

GET /v1/account/{address}

Get account information.

GET /v1/account/{address}

Description Given a specific account public key, this call returns the accounts status, balance and spendable amounts

Parameters

Type Name Description Schema
Path address
required
An account public key string

Responses

HTTP Code Description Schema
200 AccountInformationResponse contains an account information Account
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
default Unknown Error No Content

Produces

  • application/json

GET /v1/account/{address}/transaction/{txid}

Get a specific confirmed transaction.

GET /v1/account/{address}/transaction/{txid}

Description Given a wallet address and a transaction id, it returns the confirmed transaction information. This call scans up to .MaxTxnLife blocks in the past.

Parameters

Type Name Description Schema
Path address
required
An account public key string
Path txid
required
A transaction id string

Responses

HTTP Code Description Schema
200 TransactionResponse contains a transaction information Transaction
400 Bad Request string
401 Invalid API Token No Content
404 Transaction Not Found string
default Unknown Error No Content

Produces

  • application/json

GET /v1/account/{address}/transactions

Get a list of confirmed transactions.

GET /v1/account/{address}/transactions

Description Returns the list of confirmed transactions between within a date range. This call is available only when the indexer is running.

Parameters

Type Name Description Schema
Path address
required
An account public key string
Query firstRound
optional
Do not fetch any transactions before this round. integer (int64)
Query fromDate
optional
Do not fetch any transactions before this date. (enabled only with indexer) string (date)
Query lastRound
optional
Do not fetch any transactions after this round. integer (int64)
Query max
optional
maximum transactions to show (default to 100) integer (int64)
Query toDate
optional
Do not fetch any transactions after this date. (enabled only with indexer) string (date)

Responses

HTTP Code Description Schema
200 TransactionsResponse contains a list of transactions TransactionList
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
default Unknown Error No Content

Produces

  • application/json

GET /v1/account/{addr}/transactions/pending

Get a list of unconfirmed transactions currently in the transaction pool by address.

GET /v1/account/{addr}/transactions/pending

Description Get the list of pending transactions by address, sorted by priority, in decreasing order, truncated at the end at MAX. If MAX = 0, returns all pending transactions.

Parameters

Type Name Description Schema
Path addr
required
An account public key string
Query max
optional
Truncated number of transactions to display. If max=0, returns all pending txns. integer (int64)

Responses

HTTP Code Description Schema
200 PendingTransactionsResponse contains a (potentially truncated) list of transactions and
the total number of transactions currently in the pool.
PendingTransactions
401 Invalid API Token No Content
500 Internal Error string
503 Service Unavailable string
default Unknown Error No Content

Produces

  • application/json

GET /v1/asset/{index}

Get asset information.

GET /v1/asset/{index}

Description Given the asset's unique index, this call returns the asset's creator, manager, reserve, freeze, and clawback addresses

Parameters

Type Name Description Schema
Path index
required
Asset index integer (int64)

Responses

HTTP Code Description Schema
200 AssetInformationResponse contains asset information AssetParams
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
default Unknown Error No Content

Produces

  • application/json

GET /v1/assets

List assets

GET /v1/assets

Description Returns list of up to max assets, where the maximum assetIdx is <= assetIdx

Parameters

Type Name Description Schema
Query assetIdx
optional
Fetch assets with asset index <= assetIdx. If zero, fetch most recent assets. integer (int64)
Query max
optional
Fetch no more than this many assets integer (int64)

Responses

HTTP Code Description Schema
200 AssetsResponse contains a list of assets AssetList
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
default Unknown Error No Content

Produces

  • application/json

GET /v1/block/{round}

Get the block for the given round.

GET /v1/block/{round}

Parameters

Type Name Description Schema
Path round
required
The round from which to fetch block information. integer (int64)
Query raw
optional
Return raw msgpack block bytes integer (int64)

Responses

HTTP Code Description Schema
200 BlockResponse contains block information Block
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
default Unknown Error No Content

Produces

  • application/json

GET /v1/ledger/supply

Get the current supply reported by the ledger.

GET /v1/ledger/supply

Responses

HTTP Code Description Schema
200 SupplyResponse contains the ledger supply information Supply
401 Invalid API Token No Content
default Unknown Error No Content

Produces

  • application/json

GET /v1/status

Gets the current node status.

GET /v1/status

Responses

HTTP Code Description Schema
200 StatusResponse contains the node's status information NodeStatus
401 Invalid API Token No Content
500 Internal Error string
default Unknown Error No Content

Produces

  • application/json

GET /v1/status/wait-for-block-after/{round}/

Gets the node status after waiting for the given round.

GET /v1/status/wait-for-block-after/{round}/

Description Waits for a block to appear after round {round} and returns the node's status at the time.

Parameters

Type Name Description Schema
Path round
required
The round to wait until returning status integer (int64)

Responses

HTTP Code Description Schema
200 StatusResponse contains the node's status information NodeStatus
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
503 Service string
default Unknown Error No Content

Produces

  • application/json

GET /v1/transaction/{txid}

Get an information of a single transaction.

GET /v1/transaction/{txid}

Description Returns the transaction information of the given txid. Works only if the indexer is enabled.

Parameters

Type Name Description Schema
Path txid
required
A transaction id string

Responses

HTTP Code Description Schema
200 TransactionResponse contains a transaction information Transaction
400 Bad Request string
401 Invalid API Token No Content
404 Transaction Not Found string
default Unknown Error No Content

Produces

  • application/json

POST /v1/transactions

Broadcasts a raw transaction to the network.

POST /v1/transactions

Parameters

Type Name Description Schema
Body rawtxn
required
The byte encoded signed transaction to broadcast to network string (binary)

Responses

HTTP Code Description Schema
200 TransactionIDResponse contains a transaction information transactionID
400 Bad Request string
401 Invalid API Token No Content
500 Internal Error string
503 Service Unavailable string
default Unknown Error No Content

Consumes

  • application/x-binary

Produces

  • application/json

GET /v1/transactions/fee

Get the suggested fee

GET /v1/transactions/fee

Description Suggested Fee is returned in units of micro-Algos per byte. Suggested Fee may fall to zero but submitted transactions must still have a fee of at least MinTxnFee for the current network protocol.

Responses

HTTP Code Description Schema
200 TransactionFeeResponse contains a suggested fee TransactionFee
401 Invalid API Token No Content
503 Service Unavailable string
default Unknown Error No Content

Produces

  • application/json

GET /v1/transactions/params

Get parameters for constructing a new transaction

GET /v1/transactions/params

Responses

HTTP Code Description Schema
200 TransactionParamsResponse contains the parameters for
constructing a new transaction.
TransactionParams
401 Invalid API Token No Content
default Unknown Error No Content

Produces

  • application/json

GET /v1/transactions/pending

Get a list of unconfirmed transactions currently in the transaction pool.

GET /v1/transactions/pending

Description Get the list of pending transactions, sorted by priority, in decreasing order, truncated at the end at MAX. If MAX = 0, returns all pending transactions.

Parameters

Type Name Description Schema
Query max
optional
Truncated number of transactions to display. If max=0, returns all pending txns. integer (int64)

Responses

HTTP Code Description Schema
200 PendingTransactionsResponse contains a (potentially truncated) list of transactions and
the total number of transactions currently in the pool.
PendingTransactions
401 Invalid API Token No Content
500 Internal Error string
503 Service Unavailable string
default Unknown Error No Content

Produces

  • application/json

GET /v1/transactions/pending/{txid}

Get a specific pending transaction.

GET /v1/transactions/pending/{txid}

Description Given a transaction id of a recently submitted transaction, it returns information about it. There are several cases when this might succeed: - transaction committed (committed round > 0) - transaction still in the pool (committed round = 0, pool error = "") - transaction removed from pool due to error (committed round = 0, pool error != "") Or the transaction may have happened sufficiently long ago that the node no longer remembers it, and this will return an error.

Parameters

Type Name Description Schema
Path txid
required
A transaction id string

Responses

HTTP Code Description Schema
200 TransactionResponse contains a transaction information Transaction
400 Bad Request string
401 Invalid API Token No Content
404 Transaction Not Found string
503 Service Unavailable string
default Unknown Error No Content

Produces

  • application/json

GET /versions

Description Retrieves the current version

Responses

HTTP Code Description Schema
200 VersionsResponse is the response to 'GET /versions' Version

Produces

  • application/json

Definitions

Account

Account Description

Name Description Schema
address
required
Address indicates the account public key string
amount
required
Amount indicates the total number of MicroAlgos in the account integer (uint64)
amountwithoutpendingrewards
required
AmountWithoutPendingRewards specifies the amount of MicroAlgos in
the account, without the pending rewards.
integer (uint64)
assets
optional
Assets specifies the holdings of assets by this account,
indexed by the asset ID.
< string, AssetHolding > map
participation
optional
Participation
pendingrewards
required
PendingRewards specifies the amount of MicroAlgos of pending
rewards in this account.
integer (uint64)
rewards
required
Rewards indicates the total rewards of MicroAlgos the account has received, including pending rewards. integer (uint64)
round
required
Round indicates the round for which this information is relevant integer (uint64)
status
required
Status indicates the delegation status of the account's MicroAlgos
Offline - indicates that the associated account is delegated.
Online - indicates that the associated account used as part of the delegation pool.
NotParticipating - indicates that the associated account is neither a delegator nor a delegate.
string
thisassettotal
optional
ThisAssetTotal specifies the parameters of assets created by this account. < string, AssetParams > map

Asset

Asset specifies both the unique identifier and the parameters for an asset

Name Description Schema
AssetIndex
required
AssetIndex is the unique asset identifier integer (uint64)
AssetParams
required
AssetParams

AssetConfigTransactionType

AssetConfigTransactionType contains the additional fields for an asset config transaction

Name Description Schema
id
optional
AssetID is the asset being configured (or empty if creating) integer (uint64)
params
optional
AssetParams

AssetFreezeTransactionType

AssetFreezeTransactionType contains the additional fields for an asset freeze transaction

Name Description Schema
acct
required
Account specifies the account where the asset is being frozen or thawed. string
freeze
required
NewFreezeStatus specifies the new freeze status. boolean
id
required
AssetID is the asset being configured (or empty if creating) integer (uint64)

AssetList

AssetList contains a list of assets

Name Description Schema
assets
required
AssetList is a list of assets < Asset > array

AssetParams

Name Description Schema
assetname
optional
AssetName specifies the name of this asset,
as supplied by the creator.
string
clawbackaddr
optional
ClawbackAddr specifies the address used to clawback holdings of
this asset. If empty, clawback is not permitted.
string
creator
required
Creator specifies the address that created this asset.
This is the address where the parameters for this asset
can be found, and also the address where unwanted asset
units can be sent in the worst case.
string
decimals
required
Decimals specifies the number of digits to use after the decimal
point when displaying this asset. If 0, the asset is not divisible.
If 1, the base unit of the asset is in tenths. If 2, the base unit
of the asset is in hundredths, and so on.
integer (uint32)
defaultfrozen
optional
DefaultFrozen specifies whether holdings in this asset
are frozen by default.
boolean
freezeaddr
optional
FreezeAddr specifies the address used to freeze holdings of
this asset. If empty, freezing is not permitted.
string
managerkey
optional
ManagerAddr specifies the address used to manage the keys of this
asset and to destroy it.
string
metadatahash
optional
MetadataHash specifies a commitment to some unspecified asset
metadata. The format of this metadata is up to the application.
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
reserveaddr
optional
ReserveAddr specifies the address holding reserve (non-minted)
units of this asset.
string
total
required
Total specifies the total number of units of this asset. integer (uint64)
unitname
optional
UnitName specifies the name of a unit of this asset,
as supplied by the creator.
string
url
optional
URL specifies a URL where more information about the asset can be
retrieved
string

AssetTransferTransactionType

AssetTransferTransactionType contains the additional fields for an asset transfer transaction

Name Description Schema
amt
required
Amount is the amount being transferred. integer (uint64)
closeto
optional
CloseTo is the destination for remaining funds (if closing). string
id
required
AssetID is the asset being configured (or empty if creating) integer (uint64)
rcv
required
Receiver is the recipient account. string
snd
optional
Sender is the source account (if using clawback). string

Block

Block contains a block information

Name Description Schema
currentProtocol
required
CurrentProtocol is a string that represents the current protocol string
frac
optional
The number of leftover MicroAlgos after the distribution of RewardsRate/rewardUnits
MicroAlgos for every reward unit in the next round.
integer (uint64)
hash
required
Hash is the current block hash string
nextProtocol
required
NextProtocol is a string that represents the next proposed protocol string
nextProtocolApprovals
required
NextProtocolApprovals is the number of blocks which approved the protocol upgrade integer (uint64)
nextProtocolSwitchOn
required
NextProtocolSwitchOn is the round on which the protocol upgrade will take effect integer (uint64)
nextProtocolVoteBefore
required
NextProtocolVoteBefore is the deadline round for this protocol upgrade (No votes will be consider after this round) integer (uint64)
period
required
Period is the period on which the block was confirmed integer (uint64)
previousBlockHash
required
PreviousBlockHash is the previous block hash string
proposer
required
Proposer is the address of this block proposer string
rate
optional
The number of new MicroAlgos added to the participation stake from rewards at the next round. integer (uint64)
reward
optional
RewardsLevel specifies how many rewards, in MicroAlgos,
have been distributed to each config.Protocol.RewardUnit
of MicroAlgos since genesis.
integer (uint64)
round
required
Round is the current round on which this block was appended to the chain integer (uint64)
seed
required
Seed is the sortition seed string
timestamp
required
TimeStamp in seconds since epoch integer (int64)
txnRoot
required
TransactionsRoot authenticates the set of transactions appearing in the block.
More specifically, it's the root of a merkle tree whose leaves are the block's Txids, in lexicographic order.
For the empty block, it's 0.
Note that the TxnRoot does not authenticate the signatures on the transactions, only the transactions themselves.
Two blocks with the same transactions but in a different order and with different signatures will have the same TxnRoot.
string
txns
optional
TransactionList
upgradeApprove
required
UpgradeApprove indicates a yes vote for the current proposal boolean
upgradePropose
required
UpgradePropose indicates a proposed upgrade string

BuildVersion

Name Schema
branch
required
string
build_number
required
integer (int64)
channel
required
string
commit_hash
required
string
major
required
integer (int64)
minor
required
integer (int64)

KeyregTransactionType

KeyregTransactionType contains the additional fields for a keyreg Transaction

Name Description Schema
selkey
optional
SelectionPK is the VRF public key used in key registration transactions
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
votefst
optional
VoteFirst is the first round this participation key is valid integer (uint64)
votekd
optional
VoteKeyDilution is the dilution for the 2-level participation key integer (uint64)
votekey
optional
VotePK is the participation public key used in key registration transactions
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
votelst
optional
VoteLast is the last round this participation key is valid integer (uint64)

NodeStatus

NodeStatus contains the information about a node status

Name Description Schema
catchupTime
required
CatchupTime in nanoseconds integer (int64)
hasSyncedSinceStartup
required
HasSyncedSinceStartup indicates whether a round has completed since startup boolean
lastConsensusVersion
required
LastVersion indicates the last consensus version supported string
lastRound
required
LastRound indicates the last round seen integer (uint64)
nextConsensusVersion
required
NextVersion of consensus protocol to use string
nextConsensusVersionRound
required
NextVersionRound is the round at which the next consensus version will apply integer (uint64)
nextConsensusVersionSupported
required
NextVersionSupported indicates whether the next consensus version is supported by this node boolean
stoppedAtUnsupportedRound
required
StoppedAtUnsupportedRound indicates that the node does not support the new rounds and has stopped making progress boolean
timeSinceLastRound
required
TimeSinceLastRound in nanoseconds integer (int64)

Participation

Participation Description

Name Description Schema
partpkb64
required
ParticipationPK is the root participation public key (if any) currently registered for this round
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
votefst
required
VoteFirst is the first round for which this participation is valid. integer (uint64)
votekd
required
VoteKeyDilution is the number of subkeys in for each batch of participation keys. integer (uint64)
votelst
required
VoteLast is the last round for which this participation is valid. integer (uint64)
vrfpkb64
required
VRFPK is the selection public key (if any) currently registered for this round
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)

PaymentTransactionType

PaymentTransactionType contains the additional fields for a payment Transaction

Name Description Schema
amount
required
Amount is the amount of MicroAlgos intended to be transferred integer (uint64)
close
optional
CloseRemainderTo is the address the sender closed to string
closeamount
optional
CloseAmount is the amount sent to CloseRemainderTo, for committed transaction integer (uint64)
closerewards
optional
CloseRewards is the amount of pending rewards applied to the CloseRemainderTo
account as part of this transaction.
integer (uint64)
to
required
To is the receiver's address string
torewards
optional
ToRewards is the amount of pending rewards applied to the To account
as part of this transaction.
integer (uint64)

PendingTransactions

PendingTransactions represents a potentially truncated list of transactions currently in the node's transaction pool.

Name Description Schema
totalTxns
required
TotalTxns integer (uint64)
truncatedTxns
required
TransactionList

Supply

Supply represents the current supply of MicroAlgos in the system

Name Description Schema
onlineMoney
required
OnlineMoney integer (uint64)
round
required
Round integer (uint64)
totalMoney
required
TotalMoney integer (uint64)

Transaction

Transaction contains all fields common to all transactions and serves as an envelope to all transactions type

Name Description Schema
curcfg
optional
AssetConfigTransactionType
curfrz
optional
AssetFreezeTransactionType
curxfer
optional
AssetTransferTransactionType
fee
required
Fee is the transaction fee integer (uint64)
first-round
required
FirstRound indicates the first valid round for this transaction integer (uint64)
from
required
From is the sender's address string
fromrewards
optional
FromRewards is the amount of pending rewards applied to the From
account as part of this transaction.
integer (uint64)
genesisID
required
Genesis ID string
genesishashb64
required
Genesis hash
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
group
optional
Group
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
keyreg
optional
KeyregTransactionType
last-round
required
LastRound indicates the last valid round for this transaction integer (uint64)
lease
optional
Lease enforces mutual exclusion of transactions. If this field is
nonzero, then once the transaction is confirmed, it acquires the
lease identified by the (Sender, Lease) pair of the transaction until
the LastValid round passes. While this transaction possesses the
lease, no other transaction specifying this lease can be confirmed.
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
noteb64
optional
Note is a free form data
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
payment
optional
PaymentTransactionType
poolerror
optional
PoolError indicates the transaction was evicted from this node's transaction
pool (if non-empty). A non-empty PoolError does not guarantee that the
transaction will never be committed; other nodes may not have evicted the
transaction and may attempt to commit it in the future.
string
round
optional
ConfirmedRound indicates the block number this transaction appeared in integer (uint64)
tx
required
TxID is the transaction ID string
txresults
optional
TransactionResults
type
required
Type is the transaction type string

TransactionFee

TransactionFee contains the suggested fee

Name Description Schema
fee
required
Fee is transaction fee
Fee is in units of micro-Algos per byte.
Fee may fall to zero but transactions must still have a fee of
at least MinTxnFee for the current network protocol.
integer (uint64)

TransactionList

TransactionList contains a list of transactions

Name Description Schema
transactions
required
TransactionList is a list of transactions < Transaction > array

TransactionParams

TransactionParams contains the parameters that help a client construct a new transaction.

Name Description Schema
consensusVersion
required
ConsensusVersion indicates the consensus protocol version
as of LastRound.
string
fee
required
Fee is the suggested transaction fee
Fee is in units of micro-Algos per byte.
Fee may fall to zero but transactions must still have a fee of
at least MinTxnFee for the current network protocol.
integer (uint64)
genesisID
required
Genesis ID string
genesishashb64
required
Genesis hash
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$"
string (byte)
lastRound
required
LastRound indicates the last round seen integer (uint64)
minFee
optional
The minimum transaction fee (not per byte) required for the
txn to validate for the current network protocol.
integer (uint64)

TransactionResults

TransactionResults contains information about the side effects of a transaction

Name Description Schema
createdasset
optional
CreatedAssetIndex indicates the asset index of an asset created by this txn integer (uint64)

Version

Note that we annotate this as a model so that legacy clients can directly import a swagger generated Version model.

Name Description Schema
build
required
BuildVersion
genesis_hash_b64
required
Pattern : "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[A-Za-z0-9+/]{3}=)?$" string (byte)
genesis_id
required
string
versions
required
< string > array

transactionID

TransactionID Description

Name Description Schema
txId
required
TxId is the string encoding of the transaction hash string