> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/startrail-sdk-js/getting-started.md).

# Getting Started

To start development with Startrail-Sdk-Js

## NPM Package

{% embed url="<https://www.npmjs.com/package/@startbahn/startrail-sdk-js>" %}

| Env        | Tag                                                                |
| ---------- | ------------------------------------------------------------------ |
| Staging    | <https://www.npmjs.com/package/@startbahn/startrail-sdk-js/v/next> |
| Production | <https://www.npmjs.com/package/@startbahn/startrail-sdk-js>        |

{% hint style="success" %}
**Prefer to click first?** Every option on this page can be tried in the [SDK playground](https://sdk.startrail.io/) — it runs the latest release, signs in against the test network and shows the generated `new Startrail(config)` for whatever you set.
{% endhint %}

## Add Packages <a href="#implementation" id="implementation"></a>

{% tabs %}
{% tab title="npm" %}

```
npm install @startbahn/startrail-sdk-js
```

{% endtab %}

{% tab title="yarn" %}

```
yarn add @startbahn/startrail-sdk-js
```

{% endtab %}
{% endtabs %}

## Script Tag <a href="#implementation" id="implementation"></a>

{% hint style="info" %}
Please ensure to check and update to the latest version when you are developing.
{% endhint %}

{% tabs %}
{% tab title="jsdeliver" %}

```
<script src="https://cdn.jsdelivr.net/npm/@startbahn/startrail-sdk-js@2.3.0/dist/startrail-sdk.js"></script>
```

{% endtab %}

{% tab title="unpkg" %}

```
<script src="https://unpkg.com/@startbahn/startrail-sdk-js@2.3.0/dist/startrail-sdk.js"></script>
```

{% endtab %}
{% endtabs %}

## Import <a href="#implementation" id="implementation"></a>

```
const StartrailSdk = require('@startbahn/startrail-sdk-js').Startrail
// or
import StartrailSdk from "@startbahn/startrail-sdk-js";

const startrail = new StartrailSdk(config)
```

## Constructor

Configure and construct your Startrail SDK instance

```
new StartrailSdk(config)
```

### Properties

All the properties listed below are *optional*.

<table><thead><tr><th width="213">Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>apiPath</td><td><code>string</code></td><td><p>Only define it if you want to do testing. For testing use the <code>Test</code> environment URL of STARTRAIL:</p><p><code>https://api-stg.startrail.startbahn.jp/api/v1</code></p><p>For production purpose do not define it.</p></td></tr><tr><td>wallet</td><td><code>'startrail' | 'metamask'</code></td><td><p>Wallet to activate. Default is <code>startrail</code>.</p><ul><li><code>metamask</code>: MetaMask wallet installed in the user's environment.</li><li><code>startrail</code>: social (SNS) and email login powered by Web3Auth.</li></ul></td></tr><tr><td>env</td><td><code>string</code></td><td><p>The environment of Startrail-Api endpoint, blockchain network and Web3Auth environment.</p><ul><li><code>production</code>: Polygon mainnet. It is designed to communicate to Startrail production API.</li><li><code>staging</code>: Amoy testnet. It is designed to communicate to Startrail for testing.</li></ul></td></tr><tr><td>authAction</td><td><pre class="language-typescript"><code class="lang-typescript">{
  login: boolean
  signup: boolean
}
</code></pre></td><td>Which tabs the email / password popup offers and how the login modal is titled ("Login" / "Sign up"). Default: both <code>true</code>.</td></tr><tr><td>loginProvider</td><td><pre class="language-typescript"><code class="lang-typescript">['google' | 'email_passwordless' | 'facebook' | 'twitter' | 'line' | 'apple' | 'email_password']
</code></pre></td><td>Login providers for connecting the wallet, more detail <a href="/startrail-sdk-js/login-providers.md">here</a>. <strong>One</strong> provider signs in directly; <strong>several or none</strong> open the SDK's login modal.</td></tr><tr><td>loginHint</td><td><code>string</code></td><td><strong>(v2.2.0+)</strong> The user's email when it is known in advance. With a single <code>email_passwordless</code> provider, <code>login()</code> starts the passwordless flow directly and skips the modal.</td></tr><tr><td>customUi</td><td><a href="/startrail-sdk-js/login-providers/whitelabeling.md"><code>CustomUI</code></a></td><td>Brand the login modal and the wallet UI: logos, service name, wording and <strong>(v2.3.0+)</strong> <code>theme</code> — colours, light/dark mode, radii, logo placement, button style. See <a data-mention href="/startrail-sdk-js/login-providers/whitelabeling.md">Whitelabeling/Customizing</a>.</td></tr><tr><td>lang</td><td><pre class="language-typescript"><code class="lang-typescript"> 'ja' | 'en'
</code></pre></td><td>Language displayed on the UI</td></tr><tr><td>confirmationStrategy</td><td><code>'modal' | 'popup' | 'default'</code></td><td><strong>(v2.3.0+)</strong> Where sign confirmations render. <code>modal</code> (the default; <code>default</code> means the same) renders them inside the wallet iframe, immune to popup blockers. <code>popup</code> opens a separate window.</td></tr><tr><td>auth0TorusConfigKey</td><td><code>string</code></td><td>Verifier key for the <code>email_password</code> connection, resolved per <code>env</code>. Only override it with a key Startbahn gave you.</td></tr><tr><td>callbackUrl</td><td><code>string</code></td><td>A URL to which a user is redirected after completing email verification with <code>email_password</code></td></tr><tr><td>rpcEndpoint</td><td><code>string</code></td><td>An <code>rpcEndpoint</code> that is accessed from the wallet you select. See for more detail <a href="/startrail-sdk-js/getting-started/rpc-endpoint.md">here</a>.</td></tr><tr><td>chainId</td><td><code>number</code></td><td>A <code>chainId</code> that is accessed from the wallet you select. See for more detail <a href="/startrail-sdk-js/getting-started/rpc-endpoint.md">here</a>.</td></tr><tr><td>debug</td><td><code>boolean</code></td><td><strong>(v2.2.0+)</strong> Verbose SDK logging in the browser console. Default <code>false</code>.</td></tr><tr><td>withModal</td><td><code>boolean</code></td><td><strong>Deprecated (v2.3.0), no effect.</strong> The SDK's modal opens whenever <code>loginProvider</code> offers a choice. Accepted so existing configs still compile.</td></tr><tr><td>mfaLevel</td><td><code>"none" | "default" | "optional" | "mandatory"</code></td><td><strong>Deprecated (v2.2.0), no effect</strong> — the underlying wallet has no MFA level.</td></tr></tbody></table>

{% hint style="warning" %}
We recommend encouraging users to use this SDK in standard web browsers, such as Safari, Chrome, Firefox, etc. Some functionality of the SDK may not work properly in [web-views](https://en.wikipedia.org/wiki/WebView).
{% endhint %}

### Sample Config Values For Each Login Method

{% hint style="info" %}
With **no** `loginProvider` (or several), `login()` opens the SDK's login modal so the user picks a method. With **one** provider it signs in directly. Add `customUi.theme` to make the modal yours — see [whitelabeling](/startrail-sdk-js/login-providers/whitelabeling.md).
{% endhint %}

{% tabs %}
{% tab title="All" %}

```
// For Production (*No need to set apiPath)
sdk = new Startrail({
  lang: 'ja',
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name',
    theme: { mode: 'auto', accent: '#4a156c' } // v2.3.0+: brand the login modal
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="Google" %}

```
// For Production (*No need to set apiPath)
sdk = new Startrail({
  lang: 'ja',
  loginProvider: ['google'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['google'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="Email Passwordless" %}

```
// For Production (*apiPath setting is not required)
sdk = new Startrail({
  lang: 'ja',
  loginProvider: ['email_passwordless'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['email_passwordless'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="Line" %}

```
// For Production (*apiPath setting is not required)
sdk = new Startrail({
  lang: 'ja',
  loginProvider: ['line'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['line'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="Facebook" %}

```
// For Production (*apiPath setting is not required)
sdk = new Startrail({
  lang: 'ja',
  loginProvider: ['facebook'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['facebook'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="Apple" %}

```
// For Production (*apiPath setting is not required)
sdk = new Startrail({
  lang: 'ja',
  loginProvider: ['apple'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['apple'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="Twitter" %}

```
// For Production (*apiPath setting is not required)
sdk = new Startrail({
  lang: 'ja',
  loginProvider: ['twitter'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['twitter'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}

{% tab title="MetaMask" %}

```
// For Production (*No need to set apiPath)
sdk = new Startrail({
  env: 'production',
  wallet: 'metamask'
})

// For Development
sdk = new Startrail({
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  env: 'staging',
  wallet: 'metamask'
})
```

{% endtab %}

{% tab title="Email Password" %}

```
// For Production (*No need to set apiPath)
sdk = new Startrail({
  authAction: { login: false, signup: true },
  lang: 'ja',
  loginProvider: ['email_password'],
  env: 'production', // torusBuildEnv is deprecate after v1.25.0
  callbackUrl: 'https://yoursite.com', // Not necessary for login
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  }
})

// For Development
sdk = new Startrail({
  authAction: { login: false, signup: true },
  apiPath: 'https://api-stg.startrail.startbahn.jp/api/v1',
  lang: 'ja',
  loginProvider: ['email_password'],
  env: 'staging', // torusBuildEnv is deprecate after v1.25.0
  callbackUrl: 'https://yoursite.com', // Not necessary for login
  customUi: {
    logoUrl: 'https://yoursite.com/logo',
    serviceName: 'your service name'
  },
  // rpcEndpoint: 'your rpc endpoint url' // IF you want to designate endpoint
})
```

{% endtab %}
{% endtabs %}

To connect to your wallet, use `login` method

```
const eoas = await sdk.login()   // string[] on success, false when the user closes the modal
```

{% hint style="info" %}
**Returning users are restored, not re-prompted (v2.3.0+).** A new SDK instance — after a page reload, for instance — waits for the wallet to restore the previous session before showing anything. To let a user switch accounts, call `sdk.login({ loginProvider: [...], forceLogin: true })`.
{% endhint %}

See more details in [Wallet Methods](/startrail-sdk-js/wallet-methods.md)

{% hint style="info" %}
Auth0, managed by Startbahn, is used for certain authentication methods, such as Email Password.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.startrail.io/startrail-sdk-js/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.