Get Started on NEAR

Good to know: Currently, Ramper's Near SDK only supports React. A stand-alone version is under consideration.

Overview

Ramper's Near SDK provides an easy wallet solution for developers to integrate into their DApps. Once integrated, your users will be able to log in with a popular OAuth solution and instantly interact with a Near wallet.

Ramper SDK also provides WalletView component, which provides the DApp with various wallet-related functionalities such as fiat-on-ramp, transaction history and token transfers.

In addition, Ramper's Near SDK provides native support to connect your DApp with Near Wallet (more wallet supports coming soon) as well.

See these functions in action at https://example.ramper.xyz/

Initialize NEAR Wallet

To do anything with the NEAR wallet, it needs to be first funded with at least 0.1 NEAR. This is a policy set by NEAR. Whenever a user logs into your DApp through Ramper SDK, you will need to ensure that their wallet is funded.

We recommend checking their wallet balance. Either transfer 0.1 NEAR, or instruct the user to obtain NEAR. All new NEAR wallets remain inactive until initialized.

Install Ramper SDK

Setup Near JS Library

Near JS Library is useful for constructing transactions and providing a host of useful functions to interact with the Near blockchain. You can install the Near JS Library as follows:

npm i near-api-js bn.js
npm i -D @types/bn.js

Install Ramper Connect SDK

$ yarn add @ramper/near

or

$ npm i @ramper/near

User signup & login

import { 
  init, 
  signIn,
  AUTH_PROVIDER, 
  CHAIN, 
  THEME, 
  WALLET_PROVIDER,
  SUPPORTED_NEAR_NETWORKS 
} from '@ramper/near'

init({
  appName: 'Near Test App',
  authProviders: [
    AUTH_PROVIDER.GOOGLE,
    AUTH_PROVIDER.FACEBOOK,
    AUTH_PROVIDER.TWITTER,
    AUTH_PROVIDER.APPLE,
    AUTH_PROVIDER.EMAIL
  ]
  walletProviders: [WALLET_PROVIDER.NEAR_WALLET],
  network: SUPPORTED_NEAR_NETWORKS.TESTNET,
  theme: THEME.DARK,
})

const signInResult = await signIn()

Calling await signIn() will launch the log in dialog and return a signInResult when the user successfully logs in or connects an account.

Get logged in user

import { getUser } from '@ramper/near'

const user = getUser()

Displaying User Tokens

Ramper Connect SDK provides an openWallet method that opens an interface which allows the user to view their tokens, export their private key, see their transaction history, and do much more with their Ramper wallet.

import { openWallet } from '@ramper/near'  

<button onClick={openWallet}>My Wallet</button>

Once the user logs in, we recommend you replace the login button with a new button that shows their wallet address and triggers the openWallet() function when clicked.

Send token

The following code demonstrates how to send a token from a wallet belonging to the signed in user or a connected wallet.

import { sendToken } from '@ramper/near'

try {
  const isSuccess = await sendToken({
    to: '421ccd52db3465153de4591177396dc72e401b0ab1687b8c175491be32fbd148',
    value: '0.01', 
    network: 'testnet'
  })
  console.log('sendToken result: ', isSuccess)
} catch (ex) {
  console.error('Transaction failed')
}

Send transaction

The following code demonstrates how to send a transaction from a wallet belonging to the signed in user.

import { sendTransaction } from '@ramper/near'
import { transactions } from 'near-api-js'
import { BN } from 'bn.js'

try {
  const actions = [transactions.transfer(new BN(10000000))]
  await sendTransaction({
    transactionActions: [{
      receiverId: '421ccd52db3465153de4591177396dc72e401b0ab1687b8c175491be32fbd148'
      actions: actions
    }],
    network: 'testnet',
  })
} catch (ex) {
  console.error('Transaction failed')
}

Sign transaction

The following code demonstrates how to sign a transaction from a wallet belonging to the signed in user.

import { signTransaction } from '@ramper/near'

try {
  const result = await signTransaction({
    transaction: {
      receiverId: '421ccd52db3465153de4591177396dc72e401b0ab1687b8c175491be32fbd148',
      actions: [transactions.transfer(new BN(10000000))],
    },
  })
  console.log('signTransaction result', result)
} catch (e) {
  console.error(e)
}

Sign message

The following code demonstrates how to sign a transaction from a wallet belonging to the signed in user.

import { signMessage } from '@ramper/near'

const message = [12, 13, 14, 15]
const messageBuffer = new Uint8Array(message)

try {
  const result = await signMessage({
    message: messageBuffer,
  })
  console.log('signMessage result', result)
} catch (e) {
  console.log(e)
}

Sign out

Users can log out or disconnect their wallet with:

import { signOut } from '@ramper/near'

await signOut()

Yup, it really is just that easy!

If there's any feature you would like to see or design patterns you would like for the Ramper team to adopt, come chat with us (see Introduction for ways to reach us).

Boilerplate Examples

Vue

Install Dependencies:

npm i --save @ramper/near bn.js
npm i --save-dev @types/bn.js

Add near-api-js to the <HEAD> tag in your index.html. Alternatively, you can install near-api-js from npm.

<script src="https://cdn.jsdelivr.net/npm/near-api-js@0.41.0/dist/near-api-js.min.js"></script>

Sample App.vue

<script setup lang="ts">
import { AUTH_PROVIDER, CHAIN, getUser, init, openWallet, sendTransaction, signIn, signOut, THEME, WALLET_PROVIDER } from "@ramper/near";
import BN from "bn.js";
// Alternative to importing nearApi from CDN.
//import { transactions } from 'near-api-js';
</script>

<script lang="ts">

declare global {
  interface Window {
    nearApi: any
  }
}

init({
  appName: 'Near Test App',
  chainName: CHAIN.NEAR,
  walletProviders: [WALLET_PROVIDER.NEAR_WALLET],
  theme: THEME.LIGHT,
  network: 'testnet',
  authProviders: [
    AUTH_PROVIDER.GOOGLE,
    AUTH_PROVIDER.FACEBOOK,
    AUTH_PROVIDER.EMAIL
  ]
})

export default {
  components: {},
  data() {
    return {
      user: getUser()
    };
  },
  created() {},
  methods: {
    async handleSignIn(payload: MouseEvent) {
      const userData = await signIn()
      this.user = userData.user || null
    },
    handleSignOut(payload: MouseEvent) {
      signOut()
      this.user = null
    },
    openWalletView(payload: MouseEvent) {
      openWallet()
    },
    async sendSampleTransaction(payload: MouseEvent) {
      const actions = [window.nearApi.transactions.transfer(new BN(10000000))]
      const res = await sendTransaction({
        transactionActions: [
          {
            receiverId: '421ccd52db3465153de4591177396dc72e401b0ab1687b8c175491be32fbd148',
            actions: actions,
          },
        ],
        network: 'testnet',
      })
      console.log("Transaction Result: ", res)
    }
  },
};

</script>

<template>
  <main>
    <button v-if="!user" @click="handleSignIn">Sign In</button>
    <div v-if="user">
      <h1>User Info:</h1>
      <p class="box">
        {{ JSON.stringify(user) }}
      </p>
      <button @click="openWalletView">View Wallet</button>
      <button @click="sendSampleTransaction">Send Sample Transaction</button>
      <button @click="handleSignOut">Sign out</button>
    </div>
  </main>
</template>

<style scoped>
.box {
  width: 80%;
  word-break: break-all;
  padding: 20px;
}
</style>

ReactJS

import { 
  init, 
  signIn,
  signOut,
  User,
  getUser,
  openWallet,
  sendToken,
  sendTransaction,
  AUTH_PROVIDER, 
  CHAIN, 
  THEME, 
  WALLET_PROVIDER, 
  SUPPORTED_NEAR_NETWORKS 
} from '@ramper/near'
import { BN } from 'bn.js'
import { transactions } from 'near-api-js'
import { useState } from 'react'

init({
  appName: 'Near Test App',
  authProviders: [
    AUTH_PROVIDER.GOOGLE,
    AUTH_PROVIDER.FACEBOOK,
    AUTH_PROVIDER.TWITTER,
    AUTH_PROVIDER.APPLE,
    AUTH_PROVIDER.EMAIL
  ],
  walletProviders: [WALLET_PROVIDER.NEAR_WALLET],
  network: SUPPORTED_NEAR_NETWORKS.TESTNET,
  theme: THEME.DARK
})

function App() {
  const [user, setUser] = useState<User | null>(getUser())

  const handleSignIn = async () => {
    const signInResult = await signIn()
    setUser(signInResult.user ?? null)
  }

  const handleSendToken = async () => {
    try {
      const isSuccess = await sendToken({
        to: '421ccd52db3465153de4591177396dc72e401b0ab1687b8c175491be32fbd148',
        value: '0.01',
        network: 'testnet',
      })
      console.log('sendToekn result: ', isSuccess)
    } catch (e) {
      console.error(e)
    }
  }

  const handleSendTransaction = async () => {
    try {
      const actions = [transactions.transfer(new BN(10000000))]
      await sendTransaction({
        transactionActions: [
          {
            receiverId: '421ccd52db3465153de4591177396dc72e401b0ab1687b8c175491be32fbd148',
            actions: actions,
          },
        ],
        network: 'testnet',
      })
    } catch (ex) {
      console.error('Transaction failed')
    }
  }

  const handleSignOut = () => {
    signOut()
    setUser(null)
  }

  const handleOpenWalletView = () => {
    openWallet()
  }

  return (
    <div
      style={{
        padding: '20px 16px',
      }}
    >
      <div
        style={{
          display: 'flex',
          flexDirection: 'column',
        }}
      >
        <p>Ramper Near Example</p>
        <button onClick={handleSignIn}>Sign in</button>
        <br />
        <button onClick={handleSendToken}>Test sendToken</button>
        <br />
        <button onClick={handleSendTransaction}>Test sendTransaction</button>
        <br />
        <button onClick={handleOpenWalletView}>Open WalletView</button>
        <br />
        <button onClick={handleSignOut}>Sign out</button>
      </div>
    </div>
  )
}

export default App