This tutorial will help you to go through the basics to use Dogecoin Core after you completed the [installation instructions](/INSTALL.md). You now have `dogecoind` or `dogecoin-qt` executables available to run a node, and `dogecoin-cli`/`dogecoin-tx` tools to help you transact DOGE.
> **Note:** For simplicity, this guide assumes that executables can be found under the `PATH` environment variable.
If needed, you can specify their location by typing `PATH=$PATH:/path/to/executables`, or prepend the full path to the command like:
1. [Starting a dogecoin node](#starting-a-dogecoin-node)
2. [Introduction to the JSON-RPC API](#introduction-to-the-json-rpc-api)
* [Creating a wallet](#creating-a-wallet)
* [Verifying your balance](#verifying-your-balance)
* [Sending transactions](#sending-transactions)
* [Inspecting blocks and transactions](#inspecting-blocks-and-transactions)
3. [Node configuration](#node-configuration)
* [Mainnet, testnet and regtest](#mainnet-testnet-and-regtest)
* [Data directory](#data-directory)
* [RPC credentials](#rpc-credentials)
* [Ports](#ports)
* [Memory](#memory)
* [Troubleshooting](#troubleshooting)
## Starting a Dogecoin node
To start your node, you can run an headless server using `dogecoind`:
```console
shibetoshi:~$ dogecoind -daemon
```
Or you can use the Graphical User Interface (GUI), `dogecoin-qt`:
```console
shibetoshi:~$ dogecoin-qt
```
Detailed logging is recorded in `debug.log`, located in the [data directory](#data-directory).
*Use `-help` to see all available options for each executable.*
Your node is now running and starts with a *synchronization process* that downloads the entire blockchain from other nodes. This operation will take many hours to complete, but you are now part of the Dogecoin network!
> **Note:** The rest of this guide assumes the use of an headless node. The RPC server is not exposed with `dogecoin-qt` until you activate the `-server` option as a startup argument, but inside the GUI application, you can use all the commands explored below (without `dogecoin-cli`) by going to `Help -> Debug window` and inside the popup window selecting the tab `Console`.
## Introduction to the JSON-RPC API
Dogecoin Core exposes a JSON-RPC interface that allows you to request information about the network, blockchain and individual transactions, send transactions to the networks and manage your wallet.
The Dogecoin Core installation provides the `dogecoin-cli` tool to interact with the JSON-RPC from the command line, and the interface is exposed over HTTP on port `22555`, so that other tools and libraries can interact with it.
To have an overview of the available commands, use the `help` command:
```console
#List all commands
shibetoshi:~$ dogecoin-cli help
#Get help for a specific command
shibetoshi:~$ dogecoin-cli help COMMAND
```
Some commands are different, but it's possible to use the [bitcoin RPC API documentation](https://developer.bitcoin.org/reference/rpc/).
### Creating a wallet
To receive DOGE, you need an address that is securely derived from a private key through a series of automatic, cryptographic operations. The *address* can be shared with anyone to receive DOGE, but the *private key* is sensitive information that allows anyone that knows it to spend the DOGE on the associated address.
By default, the Dogecoin Core software will automatically create an address for you and securely store the private key in the wallet file.
You can list wallet addresses using `getaddressesbyaccount`:
**Tip:** Dogecoin addresses start with the letter `D`.
You now have two wallet addresses to share with other people to receive DOGE! Consider avoiding [address reuse](https://en.bitcoin.it/wiki/Address_reuse) for anonymity and security reasons.
### Verifying your balance
The total balance of all addresses held in your wallet can be found with the `getbalance` command.
```console
#Syntax
shibetoshi:~$ dogecoin-cli getbalance "*" minconf
```
`minconf` stands for minimum confirmations.
For example, to see current balance with transaction having at least 5 confirmations:
```console
shibetoshi:~$ dogecoin-cli getbalance "*" 5
421.552000
```
### Sending transactions
Dogecoin implements the [Unspent Transaction Output (UTXO)](https://en.wikipedia.org/wiki/Unspent_transaction_output) model to track which amounts of coin belong to an address. Owning DOGE means that you know the private key(s) to addresses that are associated with unspent outputs. To spend them, you have to compose a new transaction that spends the value from currently unspent outputs to new outputs.
##### sendtoaddress
It's possible to use a single command to create, sign and send a transaction :
Alternatively, four commands are needed to manually create a transaction: `listunspent`, `createrawtransaction`, `signrawtransaction` and `sendrawtransaction`.
##### listunspent
This displays a list of UTXOs associated to addresses kept in the wallet.
The `minconf` and `maxconf` parameters filter the minimum and maximum number of [confirmations](https://www.pcmag.com/encyclopedia/term/bitcoin-confirmation) of the UTXO returned.
> **Note:** The example address starts with `n` instead of `D`, because it uses [testnet](#mainnet-testnet-and-regtest).
##### createrawtransaction
You can now build a new transaction using the available UTXOs from above.
You can combine multiple UTXO and send it to multiple recipients by extending the `utxos_to_use` and recipient JSON structures.
> **Tip:** The transaction returned is encoded in hexadecimal encoding. You can use `dogecoin-cli decoderawtransaction` or `dogecoin-tx -json` to convert the content to JSON format.
##### signrawtransaction
Before sending a transaction, it must be signed by the private key that the address was derived from. Dogecoin Core will automatically use the correct private key when spending UTXO known to the wallet.
Blocks and transactions are identified by unique *hashes*.
Let's find the *[coinbase transaction](https://www.javatpoint.com/coinbase-transaction)* of block 69.
> **Note:** To be able to query transactions not related to your own wallet, like in this example, you will need to enable the `-txindex` option. This options requires the Dogecoin Core software to re-index the entire blockchain, and can take up to several hours.
Configuration can be persisted by creating a `dogecoin.conf` file. Create it in the directory defined with the `datadir` setting, `$HOME/.dogecoin` by default, or specify the file location with `-conf`.
**dogecoin.conf example :**
```
daemon=1
server=1
listen=1
paytxfee=0.01
sendfreetransactions=1
maxconnections=150
```
You can see a more concrete example [here](/contrib/debian/examples/dogecoin.conf).
### Mainnet, testnet and regtest
When trying out new things, for example to test your application that interacts with the Dogecoin chain, it is recommended to not use the main Dogecoin network. Multiple networks are built-in for this purpose.
**Mainnet** : The main network where real transaction operate.
**Testnet** : The test network, with peers.
**Regtest** : The regression test network, to test with only local peers and create blocks on-demand.
When not specifying any network, *Mainnet* is the network used by default. To enable *testnet*, use the `dogecoind -testnet`.
To enable *regtest*, use the `-regtest` option.
> **Tip:** Remember to specify the network when you want to use `dogecoin-cli`.
### Data directory
The data directory is the location where Dogecoin Core files are stored, including the wallet, log files and blocks. You can modify the location with the `-datadir` setting.
You may need to specify `-datadir` also when using `dogecoin-cli`.
See the [full documentation on file system](files.md) for more information.
### RPC credentials
Authentication is required to interact with the RPC interface. When no credentials are provided, Dogecoin uses a [random cookie](https://bitcoin.org/en/release/v0.12.0#rpc-random-cookie-rpc-authentication) that gets generated when the software is launched. It's possible to define your own credentials using `rpcuser` and `rpcpassword` parameters.
### Ports
A node can expose 2 different ports: one port for the **Peer to Peer Network** (P2P) to communicate with other nodes, and a second port for access to the RPC API. By default, the ports are configured as follows:
| Function | mainnet | testnet | regtest |
| :------- | ------: | ------: | ------: |
| P2P | 22556 | 44556 | 18444 |
| RPC | 22555 | 44555 | 18332 |
To configure them use the `-port` and `-rpcport` parameters.
### Memory
Running Dogecoin Core can require a lot of memory, so in some situations it may be necessary to optimize its usage. You can find more information about reducing the memory footprint in the [related guide](reduce-memory.md).
### Troubleshooting
By default, Dogecoin Core keeps detailed logs in the `debug.log` file, located in the `datadir`. Alternatively, the `-printtoconsole` parameter displays the log interactively to the terminal instead.
To get more verbose log output, you can enable debug mode by using the `-debug=<topic>` parameter to increase logic for a specific topic, or use `-debug=all` to see detailed logs on all topics.