Browser SDK

@fast-auth-near/browser-sdk is the framework-agnostic NEAR Auth SDK. It exposes three classes — FastAuthClient to log users in and hand you a signer, FastAuthSigner to derive keys and build NEAR actions, and FastAuthSignature to turn a raw MPC signature into transaction-ready bytes. Use it in vanilla JS, Vue, Svelte, Angular, or any web app that is not React. Pair it with a platform provider — the JavaScript provider runs the Auth0 flow in the browser. The SDK itself only depends on the IFastAuthProvider interface from @shared/core, so the same client code works regardless of which provider you construct.

FastAuthClient

FastAuthSigner

Derive keys, build actions, and submit transactions.

FastAuthSignature

Decode an MPC signature and recover its bytes.

Installation

npm install @fast-auth-near/browser-sdk @fast-auth-near/javascript-provider near-api-js

yarn add @fast-auth-near/browser-sdk @fast-auth-near/javascript-provider near-api-js

pnpm add @fast-auth-near/browser-sdk @fast-auth-near/javascript-provider near-api-js

near-api-js is a peer dependency — the SDK uses it for the NEAR Connection, transaction types, and RPC calls. You also need one provider package; on the web that is @fast-auth-near/javascript-provider.

New to NEAR Auth? Start with the quickstart for a copy-pasteable integration, then come back here for the full method surface.

Quick start

Construct a provider, hand it to a FastAuthClient, log the user in, and get a signer. Everything after login flows through the signer.

main.ts

import { FastAuthClient } from "@fast-auth-near/browser-sdk";
import { JavascriptProvider } from "@fast-auth-near/javascript-provider";
import { connect } from "near-api-js";

// 1. Build a provider for your platform (web = JavascriptProvider).
const provider = new JavascriptProvider({
  network: "testnet",
  clientId: "your-auth0-client-id",
});

// 2. Set up a NEAR connection.
const { connection } = await connect({
  networkId: "testnet",
  nodeUrl: "https://rpc.testnet.near.org",
});

// 3. Create the client with the deployed contract ids.
const client = new FastAuthClient(provider, connection, {
  fastAuthContractId: "fast-auth.testnet",
  mpcContractId: "v1.signer-prod.testnet",
});

// 4. Authenticate, then obtain an initialized signer.
await client.login();
const signer = await client.getSigner();

// 5. Derive the user's NEAR public key.
const publicKey = await signer.getPublicKey();

Contract ids live in Resources. Testnet uses fast-auth.testnet and the MPC signer v1.signer-prod.testnet; mainnet uses fast-auth.near and v1.signer.

FastAuthClient

The main entry point. FastAuthClient is a generic class that delegates authentication to the provider you pass in and produces a ready-to-use FastAuthSigner once the user is logged in.

class FastAuthClient<P extends IFastAuthProvider = IFastAuthProvider>

Constructor

constructor(
  provider: P,
  connection: Connection,
  options: FastAuthClientOptions,
)

Parameter	Type	Description
`provider`	`P extends IFastAuthProvider`	A provider instance, e.g. `JavascriptProvider`. Carries the Auth0 flow and session.
`connection`	`Connection`	A NEAR network connection from `near-api-js`.
`options`	`FastAuthClientOptions`	Contract ids the client and signer need. See below.

FastAuthClientOptions is the same shape the signer consumes:

type FastAuthClientOptions = {
  fastAuthContractId: string; // the NEAR Auth contract, e.g. "fast-auth.testnet"
  mpcContractId: string;      // the MPC signer contract, e.g. "v1.signer-prod.testnet"
};

Methods

Method	Signature	Returns	Description
`login`	`login(...args: Parameters<P["login"]>)`	Provider’s login result	Starts the provider’s login flow. Arguments are forwarded verbatim to `provider.login(...)`, so the accepted parameters match your provider.
`logout`	`logout(...args: Parameters<P["logout"]>)`	Provider’s logout result	Ends the session by delegating to `provider.logout(...)`.
`getSigner`	`getSigner(): Promise<FastAuthSigner<P>>`	`Promise<FastAuthSigner<P>>`	Verifies the user is logged in, constructs a `FastAuthSigner`, calls `init()` on it, and returns it ready to use.

getSigner() throws a FastAuthClientError with code USER_NOT_LOGGED_IN if the user is not authenticated. Call it only after login() resolves, or guard it with the provider’s isLoggedIn().

client.ts

const client = new FastAuthClient(provider, connection, {
  fastAuthContractId: "fast-auth.testnet",
  mpcContractId: "v1.signer-prod.testnet",
});

// Arguments to login() are passed straight through to the provider.
await client.login();

try {
  const signer = await client.getSigner();
  // signer is already initialized — use it directly.
} catch (error) {
  // Thrown with code USER_NOT_LOGGED_IN if the session is missing.
  console.error("Login required:", error);
}

await client.logout();

Because the client is generic over P, login and logout inherit the exact parameter types of your provider. With the JavaScript provider, login(options?, forceSelectAccount?) — see the JavaScript provider reference.

FastAuthSigner

The signer is where the NEAR-facing work happens: deriving the user’s public key, building create_account and sign actions, requesting signatures through the provider, and submitting signed transactions to the network.

class FastAuthSigner<P extends IFastAuthProvider = IFastAuthProvider>

You normally obtain a signer from client.getSigner(), which constructs it and calls init() for you. Constructing one by hand takes the same three arguments as the client and requires an explicit init().

`init`

init(): Promise<void>

Retrieves the user’s derivation path from the provider (via provider.getPath()) and stores it on the signer. Must run before any other method — getSigner() calls it automatically, so you only call it yourself when you construct a FastAuthSigner directly.

Account management

Method	Signature	Returns	Description
`createAccount`	`createAccount(accountId: string, options?: CreateAccountOptions): Promise<Action>`	`Promise<Action>`	Builds a `create_account` function-call `Action` that registers `accountId` with the user’s derived public key. Does not submit it — add the action to a transaction and send it.
`getPublicKey`	`getPublicKey(algorithm?: Algorithm): Promise<PublicKey>`	`Promise<PublicKey>`	Returns the user’s derived NEAR public key by calling the MPC contract’s `derived_public_key` method with the signer’s path and the NEAR Auth contract as predecessor.

createAccount parameters:

Parameter	Type	Default	Description
`accountId`	`string`	—	The account id to create.
`options.gas`	`bigint`	`300000000000000n` (300 TGas)	Gas attached to the `create_account` call.
`options.deposit`	`bigint`	`0n`	NEAR deposit attached to the call.
`options.algorithm`	`Algorithm`	`"ed25519"`	Which key algorithm the new account’s public key derives from.

getPublicKey parameters:

Parameter	Type	Default	Description
`algorithm`	`Algorithm`	`"ed25519"`	Selects the key derivation domain. `"ed25519"` maps to domain id `1`, `"secp256k1"` to domain id `0`.

account.ts

// Derived public key (defaults to ed25519).
const publicKey = await signer.getPublicKey();
const secpKey = await signer.getPublicKey("secp256k1");

// Build (but don't send) an account-creation action.
const action = await signer.createAccount("alice.testnet", {
  algorithm: "ed25519",
});

Requesting a signature

These two methods forward to the provider, which drives the user through Auth0 and embeds the encoded transaction into the JWT the guard contract verifies on-chain. Their parameters are inferred from your provider’s implementation.

Method	Signature	Description
`requestTransactionSignature`	`requestTransactionSignature(...args: Parameters<P["requestTransactionSignature"]>)`	Requests a signature for a NEAR transaction. Delegates to `provider.requestTransactionSignature(...)`.
`requestDelegateActionSignature`	`requestDelegateActionSignature(...args: Parameters<P["requestDelegateActionSignature"]>)`	Requests a signature for a delegate action (meta-transaction), enabling relayer-sponsored, gasless flows. Delegates to `provider.requestDelegateActionSignature(...)`.
`getSignatureRequest`	`getSignatureRequest(): Promise<GetSignatureRequestResponse>`	Returns the pending signature request the provider produced after login/redirect.

With the web provider, requesting a signature typically triggers a popup or redirect to Auth0. Persist any application state you need to survive a full-page redirect before calling these methods.

getSignatureRequest() resolves to a GetSignatureRequestResponse, which wraps the SignatureRequest alongside the resolved user:

type GetSignatureRequestResponse = {
  user: { userId: string };
  signatureRequest: SignatureRequest;
};

type SignatureRequest = {
  guardId: string;                    // JWT guard identifier
  verifyPayload: string;              // the JWT to verify on-chain
  signPayload: Uint8Array;            // the transaction bytes to sign
  algorithm?: MPCContractAlgorithm;   // "secp256k1" | "eddsa" | "ecdsa"
};

Signing and submission

Method	Signature	Returns	Description
`createSignAction`	`createSignAction(request: SignatureRequest, options?: CreateSignActionOptions): Promise<Action>`	`Promise<Action>`	Builds a `sign` function-call `Action` against the NEAR Auth contract from a `SignatureRequest`. Defaults the on-chain algorithm to `"eddsa"` when the request omits one.
`sendTransaction`	`sendTransaction(transaction: Transaction, signature: FastAuthSignature, algorithm?: Algorithm): Promise<FinalExecutionOutcome>`	`Promise<FinalExecutionOutcome>`	Recovers the signature bytes, attaches them to the transaction as a signed transaction, and broadcasts it through the connection’s RPC provider.

createSignAction parameters:

Parameter	Type	Default	Description
`request`	`SignatureRequest`	—	Contains `guardId`, `verifyPayload`, `signPayload`, and an optional `algorithm`.
`options.gas`	`bigint`	`300000000000000n` (300 TGas)	Gas attached to the `sign` call.
`options.deposit`	`bigint`	`0n`	NEAR deposit attached to the call.

sendTransaction parameters:

Parameter	Type	Default	Description
`transaction`	`Transaction`	—	The `near-api-js` transaction to sign and broadcast.
`signature`	`FastAuthSignature`	—	The MPC signature to attach — see FastAuthSignature.
`algorithm`	`Algorithm`	`"ed25519"`	The algorithm used to recover the signature bytes and pick the key type.

sign.ts

// 1. Read the pending request the provider produced.
const { signatureRequest } = await signer.getSignatureRequest();

// 2. Build the on-chain `sign` action for the NEAR Auth contract.
const signAction = await signer.createSignAction(signatureRequest);

// 3. Submit that action in a transaction to obtain the MPC signature,
//    decode it (see FastAuthSignature), then broadcast the real transaction.
const signature = FastAuthSignature.fromBase64(base64Result);
const outcome = await signer.sendTransaction(transaction, signature, "ed25519");

FastAuthSignature

A thin wrapper around the raw payload the MPC network returns. It decodes a base64 result and recovers the signature bytes in the exact format sendTransaction needs, for either curve.

class FastAuthSignature

Methods

Method	Signature	Returns	Description
`fromBase64`	`static fromBase64(base64Payload: string): FastAuthSignature`	`FastAuthSignature`	Decodes a base64 MPC payload (JSON) into a `FastAuthSignature`.
`recover`	`recover(algorithm?: Algorithm): Buffer`	`Buffer`	Recovers the signature bytes for the given curve: 64-byte ed25519 (`R‖S`) or 65-byte secp256k1 (`r‖s‖v`). Defaults to `"ed25519"`.

sendTransaction calls recover(algorithm) for you, so you rarely invoke it directly — pass the FastAuthSignature straight into sendTransaction. Call recover() yourself only when you need the raw bytes.

signature.ts

import { FastAuthSignature } from "@fast-auth-near/browser-sdk";

// Decode the MPC result returned from the `sign` call.
const signature = FastAuthSignature.fromBase64(base64Result);

// Recover raw bytes if you need them directly (defaults to ed25519).
const ed25519Bytes = signature.recover();        // 64 bytes: R‖S
const secp256k1Bytes = signature.recover("secp256k1"); // 65 bytes: r‖s‖v

Recovery is algorithm-specific. Pass the same algorithm to recover() / sendTransaction() that the account’s key was derived with — an unsupported value throws a signature error.

The `Algorithm` type

The SDK’s client-facing algorithm type is:

type Algorithm = "secp256k1" | "ed25519";

It appears on getPublicKey, createAccount options, sendTransaction, and FastAuthSignature.recover, and it defaults to "ed25519" everywhere it is optional.

The on-chain SignatureRequest.algorithm uses a distinct MPCContractAlgorithm = "secp256k1" | "eddsa" | "ecdsa" — that is the value the NEAR Auth contract’s sign method receives. createSignAction defaults it to "eddsa". Read more in How it works.

End-to-end example

Putting the three classes together: log in, derive a key, request a signature, then decode and broadcast the result.

full-flow.ts

import { FastAuthClient, FastAuthSignature } from "@fast-auth-near/browser-sdk";
import { JavascriptProvider } from "@fast-auth-near/javascript-provider";
import { connect } from "near-api-js";

const provider = new JavascriptProvider({
  network: "testnet",
  clientId: "your-auth0-client-id",
});

const { connection } = await connect({
  networkId: "testnet",
  nodeUrl: "https://rpc.testnet.near.org",
});

const client = new FastAuthClient(provider, connection, {
  fastAuthContractId: "fast-auth.testnet",
  mpcContractId: "v1.signer-prod.testnet",
});

// 1. Authenticate and obtain an initialized signer.
await client.login();
const signer = await client.getSigner();

// 2. Derive the user's NEAR public key.
const publicKey = await signer.getPublicKey();

// 3. Ask the provider to embed a transaction into the JWT and sign it.
await signer.requestTransactionSignature(/* provider-specific args */);
const { signatureRequest } = await signer.getSignatureRequest();

// 4. Build the on-chain `sign` action, submit it to get the MPC result,
//    then decode and broadcast the final transaction.
const signAction = await signer.createSignAction(signatureRequest);
const signature = FastAuthSignature.fromBase64(base64Result);
const outcome = await signer.sendTransaction(transaction, signature, "ed25519");

Next steps

JavaScript provider

The Auth0 adapter you pair with this SDK — login, redirect vs popup, and signature requests.

Core types

IFastAuthProvider, SignatureRequest, User, and the shared type surface.

Sign transactions

The full signing guide, including relayer-sponsored gasless flows.

How it works

From Auth0 JWT to on-chain verification to MPC signature.

Resources

Deployed contract ids, RPC endpoints, and network config.

SDKs overview

How the SDKs and providers compose across web and mobile.

SDKs

Providers

Reference

FastAuthClient

FastAuthSigner

FastAuthSignature

Installation

Quick start

FastAuthClient

Constructor

Methods

FastAuthSigner

`init`

Account management

Requesting a signature

Signing and submission

FastAuthSignature

Methods

The `Algorithm` type

End-to-end example

Next steps

JavaScript provider

Core types

Sign transactions

How it works

Resources

SDKs overview

FastAuthClient

FastAuthSigner

FastAuthSignature

​Installation

​Quick start

​FastAuthClient

​Constructor

​Methods

​FastAuthSigner

​init

​Account management

​Requesting a signature

​Signing and submission

​FastAuthSignature

​Methods

​The Algorithm type

​End-to-end example

​Next steps

JavaScript provider

Core types

Sign transactions

How it works

Resources

SDKs overview

Installation

Quick start

FastAuthClient

Constructor

Methods

FastAuthSigner

`init`

Account management

Requesting a signature

Signing and submission

FastAuthSignature

Methods

The `Algorithm` type

End-to-end example

Next steps