HOME/API DOCS

SmartWeb3 API Documentation

Base URL: https://api.smartweb3.xyz/v1

Authentication

Include your credentials in every request header. You receive API Key and API Secret by email after payment confirmation.

x-api-key: YOUR_API_KEY
x-api-secret: YOUR_API_SECRET
content-type: application/json

Quick Start Example

curl -X POST "https://api.smartweb3.xyz/v1/wallets" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "externalUserId": "user_1024",
    "label": "Primary wallet"
  }'

Visual API Flow

Typical SmartWeb3 integration flow from user action to blockchain result and webhook callback.

STEP 1

Auth

POST /v1/auth/validate

STEP 2

Create Wallet

POST /v1/wallets

STEP 3

Execute Action

/contracts/write or /trade/swap

STEP 4

Track Result

GET status + /v1/webhooks

Client App -> SmartWeb3 API -> Chain RPC / DEX Router
     |               |                   |
     |               +-- emits webhooks -+
     +-- polls status (/trade/orders/{id}, /wallets/{walletId}/transactions)

Authentication

Every request must include API credentials issued to your purchase email after payment confirmation.

Method	Endpoint	Usage
POST	/v1/auth/validate	Validate API credentials and fetch account profile.

Wallet Infrastructure

Create and manage passphrase-less wallets for your users.

Method	Endpoint	Usage
POST	/v1/wallets	Create a wallet for an end user.
GET	/v1/wallets/{walletId}	Get wallet details, balances, and status.
POST	/v1/wallets/{walletId}/sign	Request a transaction or message signature.
POST	/v1/wallets/{walletId}/send	Broadcast a token/native transfer transaction.
GET	/v1/wallets/{walletId}/transactions	List transaction history for a wallet.

Smart Contract Interactions

Read and write contract state without custom RPC orchestration.

Method	Endpoint	Usage
POST	/v1/contracts/read	Read view/pure function data from contracts.
POST	/v1/contracts/write	Submit contract write calls from a wallet.
POST	/v1/contracts/estimate-gas	Estimate gas before execution.
POST	/v1/contracts/events/query	Query historical contract events by filter.

Dapp Session Layer

Manage wallet-to-dapp connections and approval flows.

Method	Endpoint	Usage
POST	/v1/dapps/sessions	Create a new dapp connection session.
GET	/v1/dapps/sessions/{sessionId}	Fetch session status and metadata.
POST	/v1/dapps/sessions/{sessionId}/approve	Approve pending dapp actions.
POST	/v1/dapps/sessions/{sessionId}/reject	Reject pending dapp actions.

Decentralized Trading

Quote, route, and execute token swaps over decentralized liquidity sources.

Method	Endpoint	Usage
GET	/v1/trade/pairs	List supported token pairs per chain.
GET	/v1/trade/quote	Get best route and quote for a token swap.
POST	/v1/trade/swap	Execute a swap transaction through SmartWeb3 routing.
GET	/v1/trade/orders/{orderId}	Check swap/order execution state.

Webhooks and Usage

Track asynchronous events and monitor package consumption.

Method	Endpoint	Usage
POST	/v1/webhooks	Register a webhook endpoint for events.
GET	/v1/webhooks	List configured webhook endpoints.
DELETE	/v1/webhooks/{webhookId}	Remove an active webhook subscription.
GET	/v1/usage	Get current package usage and limits.
GET	/v1/limits	Get annual wallet/API quota limits for your package.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "chain is required",
    "requestId": "req_8f7c4b..."
  }
}