@t402/near

NEAR Protocol implementation for T402 payments using NEP-141 fungible tokens.

Installation

pnpm add @t402/near

Overview

The @t402/near package enables T402 payments on NEAR Protocol using NEP-141 token transfers. It uses the exact-direct scheme — the client executes the token transfer directly on-chain, then provides the transaction hash as proof of payment.

Key features:

Named accounts — human-readable addresses like alice.near
Direct settlement — client submits the transfer, no facilitator relay needed
NEP-141 standard — compatible with all NEAR fungible tokens

Network IDs

Network	CAIP-2 ID	RPC Endpoint
Mainnet	`near:mainnet`	`https://rpc.mainnet.near.org`
Testnet	`near:testnet`	`https://rpc.testnet.near.org`

Client Usage

import { ExactDirectNearClient } from '@t402/near/exact-direct/client'
 
const client = new ExactDirectNearClient({
  accountId: 'alice.near',
  signAndSendTransaction: async (receiverId, actions) => {
    // Use your NEAR wallet to sign and send
    const result = await wallet.signAndSendTransaction({ receiverId, actions })
    return result.transaction.hash
  }
})
 
// Create payment payload (executes transfer on-chain)
const payload = await client.createPaymentPayload(2, requirements)

Server Usage

import { ExactDirectNearServer } from '@t402/near/exact-direct/server'
 
const server = new ExactDirectNearServer({
  rpcUrl: 'https://rpc.mainnet.near.org'
})
 
// Enhance requirements with NEAR-specific fields
const enhanced = await server.enhancePaymentRequirements(baseRequirements)

Facilitator Usage

import { ExactDirectNearFacilitator } from '@t402/near/exact-direct/facilitator'
 
const facilitator = new ExactDirectNearFacilitator({
  rpcUrl: 'https://rpc.mainnet.near.org',
  indexerUrl: 'https://api.nearblocks.io' // optional
})
 
// Verify the transaction hash from client
const result = await facilitator.verify(payload, requirements)
// For exact-direct, settle is a no-op (already settled by client)
const settled = await facilitator.settle(payload, requirements)

PaymentRequirements

const requirements = {
  scheme: 'exact-direct',
  network: 'near:mainnet',
  amount: '1000000', // 1 USDT (6 decimals)
  asset: 'usdt.tether-token.near', // NEP-141 contract ID
  payTo: 'merchant.near',
  maxTimeoutSeconds: 300
}

Payment Flow

Client calls ft_transfer on the NEP-141 token contract
Client attaches 1 yoctoNEAR deposit (required by NEP-141)
Transaction executes on NEAR
Client returns the txHash as proof of payment
Facilitator verifies the transaction via RPC or indexer

The exact-direct scheme means the client settles the payment directly on-chain. The facilitator only verifies the transaction — it does not relay or execute it.

Token Addresses

Token	Network	Contract ID	Decimals
USDT	Mainnet	`usdt.tether-token.near`	6
USDC	Mainnet	`17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1`	6
USDC	Testnet	`usdc.fakes.testnet`	6

Payload Structure

interface ExactDirectNearPayload {
  txHash: string;   // base58 transaction hash
  from: string;     // sender account ID
  to: string;       // recipient account ID
  amount: string;   // amount in smallest units
}

Error Codes

Code	Description
`invalid_payload_structure`	Missing txHash, from, to, or amount
`network_mismatch`	Transaction network doesn’t match requirements
`amount_mismatch`	Transferred amount less than required
`recipient_mismatch`	Transfer recipient doesn’t match payTo
`transaction_not_found`	Transaction hash not found on-chain
`transaction_failed`	Transaction exists but failed

Example: Full Integration

import { t402Client } from '@t402/fetch'
import { registerExactDirectNearClient } from '@t402/near/exact-direct/client'
 
const client = new t402Client()
registerExactDirectNearClient(client, {
  accountId: wallet.accountId,
  signAndSendTransaction: wallet.signAndSendTransaction
})
 
const response = await client.fetch('https://api.example.com/premium')

Go SDK

import "github.com/t402-io/t402/sdks/go/mechanisms/near"
 
// Client
client := near.NewExactDirectNearScheme(signer, &near.ExactDirectNearClientConfig{
    GasAmount: "30000000000000", // 30 TGas
})
payload, err := client.CreatePaymentPayload(ctx, requirements)
 
// Facilitator
facilitator := near.NewExactDirectNearFacilitator(rpcURL)
result, err := facilitator.Verify(ctx, payload, requirements)

@t402/tron @t402/aptos