feat: add NEAR docs (#3)

Co-authored-by: Copilot <[email protected]>

Author: MantisClone

.gitignore

@@ -0,0 +1 @@
+/ignore

api-features/payment-detection.mdx

@@ -154,4 +154,4 @@ Requests progress through the following payment states:
   >
     View all supported networks and currencies
   </Card>
-</CardGroup>
+</CardGroup>

docs.json

@@ -127,6 +127,7 @@
             "group": "🌐 Developer Resources",
             "pages": [
               "resources/supported-chains-and-currencies",
+              "resources/near-blockchain",
               "resources/token-list",
               "resources/community"
             ]

resources/near-blockchain.mdx

@@ -0,0 +1,168 @@
+---
+title: "NEAR (SDK Only)"
+description: "Request Network's support for NEAR including native and fungible token payments"
+---
+
+import { CopyButton, ExternalLinkButton } from "/snippets/contract-buttons.jsx"
+
+## Overview
+
+Request Network supports payments on NEAR, a sharded, proof-of-stake blockchain that offers unique capabilities compared to EVM-compatible chains. NEAR's architecture enables more complex smart contract interactions through asynchronous callbacks and cross-contract calls.
+
+<Note>
+NEAR support is currently available through the **Request Network SDK only**. The Request Network API does not support NEAR blockchain interactions.
+</Note>
+
+## Key Differences from EVM Chains
+
+NEAR has several important architectural differences that affect how payments work:
+
+<CardGroup cols={2}>
+  <Card title="Asynchronous Callbacks" icon="arrows-rotate">
+    Unlike EVM chains where transactions are atomic, NEAR supports **asynchronous callbacks** that can span multiple transactions or blocks. This enables more complex payment flows but requires different handling.
+  </Card>
+  
+  <Card title="Account-Based System" icon="user">
+    NEAR uses human-readable account names (like `alice.near`) instead of hex addresses. Smart contracts are deployed to named accounts and can be upgraded by their owners.
+  </Card>
+</CardGroup>
+
+<CardGroup cols={2}>
+  <Card title="Storage Deposits" icon="database">
+    To receive NEP-141 fungible tokens, accounts must first register with the token contract and pay a small storage deposit (~0.00125 NEAR) to cover storage costs.
+  </Card>
+  
+  <Card title="Gas Model" icon="gas-pump">
+    NEAR uses a different gas model with TGas (TeraGas) units. Gas costs are predictable and much lower than Ethereum mainnet.
+  </Card>
+</CardGroup>
+
+## Supported Payment Types
+
+### Native NEAR Payments
+
+Direct payments using NEAR's native token through the payment proxy smart contract.
+
+**Features:**
+- ✅ Direct NEAR token transfers with payment references
+- ✅ Fee collection support
+- ✅ Payment detection and indexing
+
+### Fungible Token Payments (NEP-141)
+
+Payments using NEAR's fungible token standard (NEP-141) equivalent to ERC-20 on Ethereum.
+
+**Features:**
+- ✅ Support for all NEP-141 compliant tokens
+- ✅ Fee collection in the same token
+- ✅ Payment detection and indexing
+- ⚠️ Requires storage deposit registration
+
+### Native Token Conversion Payments
+
+Payments for requests denominated in one currency (typically fiat like USD) but paid in NEAR native tokens. On-chain oracles provide real-time price feeds to calculate the correct NEAR amount.
+
+**Features:**
+- ✅ Conversion payments denominated in USD, settled in NEAR
+- ✅ Price conversion at the moment of payment, using onchain price feeds
+- ✅ Payment detection and indexing
+
+## Smart Contract Addresses
+
+### Mainnet (near)
+
+| Payment Type | Contract Address | Actions | Description |
+|--------------|------------------|---------|-------------|
+| **Native NEAR Payments** | `requestnetwork.near` | <div className="flex gap-1"><CopyButton text="requestnetwork.near" /><ExternalLinkButton href="https://nearblocks.io/address/requestnetwork.near" /></div> | Direct NEAR token payments with references |
+| **Fungible Token Payments** | `pay.reqnetwork.near` | <div className="flex gap-1"><CopyButton text="pay.reqnetwork.near" /><ExternalLinkButton href="https://nearblocks.io/address/pay.reqnetwork.near" /></div> | NEP-141 token payments with fees |
+| **Native Conversion Payments** | `native.conversion.reqnetwork.near` | <div className="flex gap-1"><CopyButton text="native.conversion.reqnetwork.near" /><ExternalLinkButton href="https://nearblocks.io/address/native.conversion.reqnetwork.near" /></div> | Fiat/token to NEAR conversions |
+
+### Testnet (near-testnet)
+
+| Payment Type | Contract Address | Actions | Description |
+|--------------|------------------|---------|-------------|
+| **Native NEAR Payments** | `dev-1631521265288-35171138540673` | <div className="flex gap-1"><CopyButton text="dev-1631521265288-35171138540673" /><ExternalLinkButton href="https://testnet.nearblocks.io/address/dev-1631521265288-35171138540673" /></div> | Direct NEAR token payments with references |
+| **Fungible Token Payments** | `pay.reqnetwork.testnet` | <div className="flex gap-1"><CopyButton text="pay.reqnetwork.testnet" /><ExternalLinkButton href="https://testnet.nearblocks.io/address/pay.reqnetwork.testnet" /></div> | NEP-141 token payments with fees |
+| **Native Conversion Payments** | `native.conversion.reqnetwork.testnet` | <div className="flex gap-1"><CopyButton text="native.conversion.reqnetwork.testnet" /><ExternalLinkButton href="https://testnet.nearblocks.io/address/native.conversion.reqnetwork.testnet" /></div> | Fiat/token to NEAR conversions |
+
+## Payment Detection
+
+Payment detection for NEAR transactions is handled through dedicated subgraphs:
+
+- **NEAR Mainnet**: [Request Payments Near Subgraph](https://thegraph.com/explorer/subgraphs/9yEg3h46CZiv4VuSqo1erMMBx5sHxRuW5Ai2V8goSpQL?view=Query&chain=arbitrum-one)
+- **NEAR Testnet**: [Request Payments Near Testnet Subgraph](https://thegraph.com/explorer/subgraphs/AusVyfndonsMVFrVzckuENLqx8t6kcXuxn6C6VbSGd7M?view=Query&chain=arbitrum-one)
+
+These subgraphs index payment events and transaction data to enable efficient payment detection and status tracking.
+
+## Technical Considerations
+
+### Asynchronous Callbacks
+
+NEAR's asynchronous architecture means payment transactions may require multiple blockchain interactions:
+
+```javascript
+// Example: Fungible token payment flow
+1. Call ft_transfer_call on token contract
+2. Token contract calls proxy contract 
+3. Proxy processes payment and logs event
+4. Callback confirms or reverts transaction
+```
+
+This differs from EVM chains where the entire payment happens in a single atomic transaction.
+
+### Storage Deposits
+
+Before receiving NEP-141 tokens, accounts must register with the token contract:
+
+<Warning>
+**Important**: Payment addresses must have sufficient storage deposit registered with the token contract. The SDK automatically checks for this requirement and will throw an error if the recipient is not properly registered.
+</Warning>
+
+**Minimum Storage Deposit**: ~0.00125 NEAR per token contract
+
+### Gas Considerations
+
+<Tip>
+NEAR uses a TGas (TeraGas) unit system and gas costs are predictable and much lower than Ethereum mainnet, typically costing fractions of a cent in USD terms.
+</Tip>
+
+## Integration Guide
+
+### Prerequisites
+
+1. **NEAR Wallet Connection**: Applications need to integrate with NEAR wallet providers
+2. **SDK Installation**: Use `@requestnetwork/request-client.js` with NEAR support
+3. **Account Registration**: Ensure payment recipients are registered for token contracts
+
+### Basic Payment Flow
+
+```javascript
+import { RequestNetwork } from '@requestnetwork/request-client.js';
+
+// Create request for NEAR native payment
+const request = await requestNetwork.createRequest({
+  currency: {
+    type: 'ETH', // NEAR native uses ETH type
+    value: 'NEAR',
+    network: 'near'
+  },
+  expectedAmount: '1000000000000000000000000', // 1 NEAR in yoctoNEAR
+  paymentAddress: 'recipient.near'
+});
+```
+
+## Limitations
+
+<Warning>
+**Current Limitations:**
+- NEAR support is SDK-only (not available in Request Network API)
+- Crosschain payments to/from NEAR are not supported
+- Advanced payment types like batch payments are not implemented
+</Warning>
+
+## Developer Resources
+
+- [NEAR Documentation](https://docs.near.org/)
+- [NEP-141 Fungible Token Standard](https://nomicon.io/Standards/Tokens/FungibleToken/Core)
+- [NEAR Smart Contract Source Code](https://github.com/RequestNetwork/near-contracts)
+- [Request Network SDK Documentation](https://docs.request.network/advanced/request-network-sdk)

resources/supported-chains-and-currencies.mdx

@@ -78,6 +78,14 @@ For a complete, machine-readable list of all supported tokens with contract addr
   </Card>
 </CardGroup>
 
+<Warning>
+**NEAR Blockchain Support (SDK Only)**
+
+Request Network also supports the NEAR blockchain, but **only through the Request Network SDK** (not the API). NEAR's unique architecture requires different integration patterns.
+
+[Learn more about NEAR support →](/resources/near-blockchain)
+</Warning>
+
 ## Currency Categories
 
 ### Major Cryptocurrencies

snippets/contract-buttons.jsx

@@ -0,0 +1,110 @@
+export const CopyButton = ({ text, title = "Copy Address" }) => {
+  const handleCopy = (e) => {
+    const button = e.currentTarget;
+    const svg = button.querySelector('svg');
+    
+    if (!navigator.clipboard || !svg) return;
+    
+    // Store original SVG
+    const originalSVG = svg.outerHTML;
+    
+    // Copy to clipboard
+    navigator.clipboard.writeText(text).then(() => {
+      // Show checkmark
+      svg.outerHTML = `
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+          <polyline points="20 6 9 17 4 12"></polyline>
+        </svg>
+      `;
+      button.setAttribute('data-copied', 'true');
+      
+      // Reset after 2 seconds
+      setTimeout(() => {
+        const checkmark = button.querySelector('svg');
+        if (checkmark) {
+          checkmark.outerHTML = originalSVG;
+        }
+        button.removeAttribute('data-copied');
+      }, 2000);
+    }).catch(() => {
+      // Silent fail
+    });
+  };
+
+  return (
+    <button 
+      onClick={handleCopy}
+      title={title}
+      aria-label={title}
+      className="inline-flex items-center justify-center w-8 h-8 text-gray-600 dark:text-gray-400 transition-all duration-200 rounded-md hover:bg-gray-100 dark:hover:bg-gray-700 focus:outline-none"
+      style={{
+        '--primary-color': '#01B089'
+      }}
+    >
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+        <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+        <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+      </svg>
+      <style jsx>{`
+        button[data-copied="true"] {
+          color: #10b981 !important;
+        }
+        button:hover {
+          color: var(--primary-color) !important;
+        }
+        button:focus {
+          color: var(--primary-color) !important;
+          box-shadow: 0 0 0 2px var(--primary-color) !important;
+        }
+      `}</style>
+    </button>
+  );
+};
+
+export const ExternalLinkButton = ({ href, title = "View on Block Explorer" }) => {
+  // Validate URL to prevent XSS/open redirects
+  const isValidUrl = (url) => {
+    try {
+      const parsed = new URL(url);
+      return ['http:', 'https:'].includes(parsed.protocol);
+    } catch {
+      return false;
+    }
+  };
+
+  if (!isValidUrl(href)) {
+    console.error('Invalid URL provided to ExternalLinkButton:', href);
+    return null;
+  }
+
+  return (
+    <a 
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      title={title}
+      aria-label={title}
+      className="inline-flex items-center justify-center w-8 h-8 text-gray-600 dark:text-gray-400 transition-all duration-200 rounded-md hover:bg-gray-100 dark:hover:bg-gray-700 focus:outline-none no-underline"
+      style={{
+        textDecoration: 'none',
+        borderBottom: 'none',
+        '--primary-color': '#01B089'
+      }}
+    >
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+        <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path>
+        <polyline points="15,3 21,3 21,9"></polyline>
+        <line x1="10" y1="14" x2="21" y2="3"></line>
+      </svg>
+      <style jsx>{`
+        a:hover {
+          color: var(--primary-color) !important;
+        }
+        a:focus {
+          color: var(--primary-color) !important;
+          box-shadow: 0 0 0 2px var(--primary-color) !important;
+        }
+      `}</style>
+    </a>
+  );
+};

use-cases/subscriptions.mdx

@@ -326,4 +326,4 @@ app.post('/webhook/subscription', (req, res) => {
   >
     Set up your account for subscription billing
   </Card>
-</CardGroup>
+</CardGroup>