s3s 🦑

s3s is a script that uploads Splatoon 3 battle data from the SplatNet 3 service (part of the Nintendo Switch Online app) to stat.ink, a site for recording, visualizing, and aggregating statistics from the Splatoon series of games.

(ja) 日本語版セットアップ手順はこちら、またはこちら。

Looking to track your Splatoon 2 gameplay? See splatnet2statink.

Features

• Full automation of SplatNet token generation via user log-in
• Ability to parse & upload complete battle/job stats to stat.ink (example profile)
• Support for Salmon Run Next Wave and Big Run
• Support for Splatfest & Tricolor Turf War battles and Challenges
• Monitoring for new results in real-time & checking for missing/unuploaded results
• Flag to remove other players' names from results
• Support for all available game languages
• File exporting function for use with Lean's seed checker tools
• Modular design to support IkaLog3 and other tools

What's coming?

• Easier setup via downloadable, pre-packaged program executables (soon!)

Usage 🐙

$ python s3s.py [-M [N]] [-r] [-nsr | -osr] [--blackout]

The -M flag runs the script in monitoring mode, uploading new matches as you play, checking for new results every N seconds; if no N is provided, it defaults to 300 (5 minutes).

The -r flag checks for & uploads any battles/jobs present on SplatNet 3 that haven't yet been uploaded.

The -nsr flag makes Salmon Run jobs not be monitored/uploaded. Use this if you're playing Lobby modes only.

The -osr flag, conversely, makes only Salmon Run jobs be monitored/uploaded. Use this if you're playing at Grizzco only.

The --blackout flag removes other players' names from uploaded scoreboard data.

Arguments for advanced usage (e.g. locally exporting data to JSON files, use with with Lean's seed checker tools) can be viewed using --help.

Tips for using s3s

★ On first run, you'll want to use the -r flag to upload all available data from SplatNet to stat.ink, i.e. up to 250 battles (50 of each type: Turf War, Anarchy, X, Challenge, and Private) and up to 50 recent Salmon Run jobs.

The suggested usage of s3s is in monitoring mode, where you run the script as you play the game and exit it once you're done playing. The command python s3s.py -r -M first looks to ensure there's no data missing from stat.ink (uploading it if so), and then continues in monitoring mode while checking for new results every 5 minutes.

More specific use cases can be specified using other flags (and config keys). For example, if you're solely playing Salmon Run and only want to check for new results every 15 minutes, you would use python s3s.py -osr -M 900. If not using monitoring mode, python s3s.py -r should be run at least once every 50 matches to ensure no data is lost.

Setup instructions 🔰

1. Download and install Python 3. On Windows, grab the latest release from Python.org and check the option during setup to add it to your PATH. On macOS, install Homebrew and run brew install python from Terminal. Run python --version to verify the installation.

2. If you're on Windows, install Git (pre-installed on macOS and Linux).

3. Download the script from the command line (macOS: Terminal; Windows: Command Prompt/PowerShell) by running git clone https://github.com/frozenpandaman/s3s.git.

4. Navigate to the newly-created directory (type cd s3s/) and install the required Python libraries by running pip install -r requirements.txt. On Windows, you may have to use python -m pip instead.

5. Running the script for the first time (see the "Usage" section above →) will prompt you to enter your stat.ink API Token (available in settings). If you're playing the game in a language other than English, you may enter your language code (locale) as well.

NOTE: Read the "Token generation" section below before proceeding. →

6. You will then be asked to navigate to a specific URL on Nintendo.com, log in, and follow simple instructions to obtain your session_token; this will be used to generate a gtoken and bulletToken. If you are opting against automatic token generation, enter "skip" for this step, at which point you will be asked to manually input your two tokens instead (see the mitmproxy instructions).

   These tokens (used to access your SplatNet battle results) along with your stat.ink API key & language will be saved into config.txt for you. You're now ready to upload battles!

Have any questions, problems, or suggestions? Create an issue here or contact me on Twitter. Please do not raise issues via Discord. It is important for discussion on the internet to be public, indexable, and searchable, able to be shared freely and benefit others – not locked behind a private platform. Here's a great article about this!

質問があれば、ツイッター(@frozenpandaman)で連絡してください。日本語OK。

Accessing SplatNet 3 from your browser

If you wish to access SplatNet 3 from your computer rather than via the phone app, navigate to https://api.lp1.av5ja.srv.nintendo.net/ (it should show server maintenance). Use your browser or a third-party extension to add a cookie (Chrome instructions here) named _gtoken. Set it to the value you obtained previously (automatically by running the script or via mitmproxy) – stored as gtoken in config.txt – and refresh the page. If you only want to access SplatNet and don't have a stat.ink API key, simply enter "skip" for this step during setup.

To access SplatNet 3 in a language other than English, go to https://api.lp1.av5ja.srv.nintendo.net/?lang=xx-XX where xx-XX is one of the available language codes.

You can even enter QR codes on the web version of SplatNet 3 via the list of available ones here!

Splatoon 3 stage rotation information, Splatfest data, and current SplatNet gear are viewable at splatoon3.ink.

Token generation 🪙

For s3s to work, tokens known as gtoken and bulletToken are needed to access SplatNet. These tokens may be obtained automatically, using the script, or manually via the official Nintendo Switch Online app. Please read the following sections carefully to decide whether or not you want to use automatic token generation.

Automatic

Automatic token generation involves making a secure request to a non-Nintendo server with minimal, non-identifying information. We aim to be 100% transparent about this and provide in-depth information on security and privacy. Users who feel uncomfortable with this may opt to manually acquire their tokens instead.

Privacy statement: No identifying information is ever sent to the imink API. Usernames and passwords are far removed from where the API comes into play and are never readable by anyone but you, and returned values do not contain any meaningful information about your account. It is not possible to use either sent or stored data to identify which account/user performed a request, to view identifying information about a user, or to gain access to an account. See the imink API Privacy Policy and Documentation for more information.

Alternatively, you can use nsotokengen or nxapi-znca-api as a drop-in replacement (customizable in config.txt) to generate tokens locally, i.e. without calls to a third-party API.

Manual

Users who decide against using automatic token generation may instead retrieve tokens manually via SplatNet 3.

In this case, users must obtain tokens from their phone – or an emulator – by intercepting their device's web traffic and entering the tokens into s3s when prompted (or manually adding them to config.txt later). Follow the mitmproxy instructions to obtain your tokens. To opt for manual token entry, type "skip" when prompted to enter the "Select this account" URL.

License & copyleft statement 🏴

s3s is free software licensed under GPLv3. This means that you have freedom – to run, modify, copy, share, and redistribute this work as you see fit, as long as derivative works are also distributed under these same or equivalent terms.

Copyright is a recent, confusing, and often unnecessary human invention. Libraries, for example, predate copyright by thousands of years, and their integral role in the "promotion of science" and "encouragement of learning" was acknowledged even before the first copyright statutes were enacted. If the first human who had the idea of a hammer claimed it as their intellectual property, we wouldn't have gotten very far as a species. Please consider sharing your work openly with the world. (statement adapted from here and here)

While this is a free/libre and open-source project, its license does require attribution. If you are using any part of s3s, splatnet2statink, iksm.py, etc. in your project, please provide a link back to this repository. I have spent over half a decade and hundreds of hours of my personal time on these projects for the Splatoon community – so, at the least, some credit would be nice. :) Donations, via the "Sponsor" button at the top or links in the sidebar, are also greatly appreciated. Thank you, and stay fresh! –eli ＜コ:彡