Can You Add a BitTorrent to aria2 via XML-RPC?

This article provides a direct guide on how to add a new BitTorrent download to a running aria2 daemon using XML-RPC calls. We will explore the specific method required, the format the torrent file must take, and a practical example of a request payload. By the end of this guide, you will understand how to interact with the aria2 API to automate and manage your torrent downloads remotely.

The Short Answer: Yes

It is entirely possible to add a BitTorrent download to an aria2 daemon using XML-RPC. The aria2 daemon exposes a robust API that allows for full control over downloads, including HTTP, FTP, Metalink, and BitTorrent.

To add a BitTorrent download, you utilize the aria2.addTorrent method.

Understanding the `aria2.addTorrent` Method

Unlike adding a standard HTTP URL, you cannot simply pass a URL of a .torrent file directly to the standard download method if you want aria2 to treat it as a local torrent structure immediately. Instead, the aria2.addTorrent method expects the actual content of the torrent file to be uploaded within the XML-RPC body.

Because XML cannot handle raw binary data safely, the torrent file must be converted into a Base64-encoded string before being placed into the XML payload.

Required Parameters:

Secret Token (Optional but Recommended): If your aria2 daemon is secured with a token (--rpc-secret), this must be the first parameter, prefixed with token:.
Torrent Data: The Base64-encoded string of the .torrent file contents.
URIs (Optional): An array of webseed URIs. If you don’t have any, this is passed as an empty array.
Options (Optional): A struct/dictionary containing specific aria2 options for this download (e.g., download speed limits, save directory).

Structure of the XML-RPC Request

When constructing the XML-RPC POST request, the methodName tag must be set to aria2.addTorrent. Below is an example of how the XML payload looks when sending the command to a daemon secured with a token.

<?xml version="1.0"?>
<methodCall>
  <methodName>aria2.addTorrent</methodName>
  <params>
    <param>
      <value><string>token:YOUR_RPC_SECRET_HERE</string></value>
    </param>
    <param>
      <value><string>4Yid0b3JyZW50X0Jhc2U2NF9FbmNvZGVkX0RhdGE...</string></value>
    </param>
    <param>
      <value>
        <array>
          <data></data>
        </array>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>dir</name>
            <value><string>/downloads/torrents</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Key Workflow Implementation Steps

To successfully execute this in your application or script, follow these steps:

Read the file: Open your local .torrent file and read its raw binary data.
Encode to Base64: Convert that binary data into a standard Base64 string.
Build the XML: Insert the string into the second <param> block of your XML structure.
Send the POST Request: Send the XML payload via an HTTP POST request to the aria2 RPC endpoint (typically http://localhost:6800/rpc).

Upon a successful call, the aria2 daemon will return an XML response containing a GID (Graphics Interchange Identifier), which is a unique string hex identifier for the newly created BitTorrent download download task. You can use this GID to pause, stop, or check the status of the torrent later.