Wallet OpenAPI Quick Start

Integration Sequence Diagram

Take a wallet application as an example:

sequenceDiagram
    participant User
    participant App
    participant Backend
    participant Dashboard as Dashboard
    participant WOS as Wallet OpenAPI Service
    participant Blockchain

    %% Preparation Phase - Dashboard Configuration
    rect rgb(191, 223, 255)
    note over Dashboard,Backend: Preparation Phase - Dashboard Configuration
    Backend ->> Dashboard: 1. Register account
    Dashboard -->> Backend: Registration completed
    Backend ->> Dashboard: 2. Create application
    Dashboard -->> Backend: Return App info
    Backend ->> Dashboard: 3. Register API Key
    Dashboard -->> Backend: API Key configured
    Backend ->> Dashboard: 4. Configure Webhook
    Dashboard -->> Backend: Webhook configured
    end

    %% Preparation Phase - SDK Integration
    rect rgb(230, 230, 200)
    note over App,Backend: Preparation Phase - SDK Integration
    App ->> Backend: 5. Create wallet
    Backend ->> WOS: 6. Call create wallet API
    WOS -->> Backend: Return wallet info
    Backend -->> App: Return wallet info
    end

    %% Deposit Phase
    rect rgb(200, 255, 200)
    note over User,Blockchain: Deposit Phase
    User ->> App: 7. Get deposit address
    App ->> Backend: 8. Request deposit address
    Backend ->> WOS: 9. Get deposit address API
    WOS -->> Backend: Return deposit address
    Backend -->> App: Return deposit address
    App -->> User: Display deposit address
    User ->> Blockchain: 10. Transfer to deposit address
    Blockchain ->> WOS: 11. On-chain confirmation
    WOS ->> Backend: 12. Webhook callback (deposit success)
    end

    %% Withdrawal Phase
    rect rgb(255, 230, 200)
    note over User,Blockchain: Withdrawal Phase
    User ->> App: 1. Initiate withdrawal request
    App ->> Backend: 2. Submit withdrawal
    Backend ->> WOS: 3. Create withdrawal transaction API
    WOS ->> Blockchain: 4. Submit on-chain transaction
    Blockchain -->> WOS: 5. Transaction confirmation
    WOS ->> Backend: 6. Webhook callback (withdrawal result)
    end

    %% Transfer Phase
    rect rgb(230, 200, 255)
    note over User,WOS: Transfer Phase
    User ->> App: 1. Initiate transfer request
    App ->> Backend: 2. Submit internal transfer
    Backend ->> WOS: 3. Create transfer API
    WOS ->> WOS: 4. Execute internal transfer
    WOS ->> Backend: 5. Webhook callback (transfer result)
    end

Dashboard Operation Instructions

Dashboard is the management backend for Wallet OpenAPI, providing functions such as creating applications, configuring applications, and managing wallets.

You can consult our customer service for the access address of the Dashboard.

Technical Support TG: @Openweb3Wallet

Dashboard entry links: https://wallet.openapi.openweb3.io

Register Account

You can register with an email or log in with Google, and follow the instructions to complete the 2FA registration and binding.

Create Application

After logging into Dashboard, click Apps -> New App to create a new application.

Configure Application

Register `API Key`

If you need to use the SDK to make OpenApi interface calls, including creating wallets, querying balances, etc., you need to register an API Key in the Dashboard first.

The ED25519 algorithm APIKEY is used here. You can refer to the following method to generate the key pair:

# Generate a private key and save it to `private.key.pem` file
openssl genpkey -algorithm ed25519 -out private_key.pem

# Extract the public key from the private key and save it to `public.key.pem` file
openssl pkey -in private_key.pem -pubout -out public_key.pem

# Export the private key in hexadecimal format
openssl pkey -in private_key.pem -text | \
grep 'priv:' -A 3 | tail -n +2 | tr -d ':\n '

# Export the public key in hexadecimal format
openssl pkey -pubin -in public_key.pem -text | \
grep 'pub:' -A 3 | tail -n +2 | tr -d ':\n '

After the key pair is generated, register the public key to the application through Apps -> App Settings -> Register API Key.

The private key needs to be kept properly by yourself and will be used when using the SDK.

Configure `Webhook`

If you need to use Webhook for transaction status callback notifications, you need to configure Webhook in the Dashboard first.

Add a webhook endpoint in Apps -> App Settings -> Add Webhook.

API Overview

Wallet OpenAPI service provides complete wallet management functionality:

Wallet Management - Create, Query, Update, List wallets
Deposit Addresses - Get and manage deposit addresses
Transaction Management - Deposit, Withdraw, Transfer, Query transactions
Currency Management - Query supported currencies and networks
Rate Service - Query currency exchange rates and estimates
Webhooks - Real-time transaction event notifications

Base Information

API Address: https://api.wallet.openweb3.io
API Version: v1
Authentication: ED25519 signature (handled automatically by SDK)

Error Codes

HTTP Status Code	Description
400	Invalid request parameters
401	Authentication failed
404	Resource not found
500	Internal server error

Authentication Mechanism

The SDK handles authentication signature automatically. You only need to provide ApiKey and Secret.

Signature Algorithm

The SDK uses ED25519 signature algorithm internally:

Concatenate signature data: body + uri + requestTime
Calculate SHA256 hash
Sign with ED25519 private key
Hex encode the signature

For manual signature reference:

Signature Example (Golang):

import (
    "crypto/ed25519"
    "encoding/hex"

    wallet "github.com/openweb3-io/wallet-openapi/go/crypto"
)

func sign(body, uri, requestTime string, privateKey ed25519.PrivateKey) string {
    data := body + uri + requestTime
    hash := crypto.Hash256([]byte(data))
    sig, _ := wallet.NewEd25519Signer(privateKey).Sign(hash)
    return hex.EncodeToString(sig)
}

SDK Integration

Golang SDK Installation

go get github.com/openweb3-io/wallet-openapi/go

Golang SDK Initialization

import (
    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func main() {
    // Initialize client
    apiKey := "YOUR_API_KEY"
    secret := "YOUR_SECRET"

    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: apiKey,
        Secret: secret,
    })

    // Client contains the following services:
    // - client.Wallet     // Wallet management
    // - client.Address    // Address management
    // - client.Currency   // Currency management
    // - client.Rate       // Rate service
    // - client.Transaction // Transaction management
    // - client.WebhookEndpoint  // Webhook endpoint management
    // - client.WebhookEventTypes // Webhook event types
    // - client.WebhookEvents    // Webhook events
    // - client.ChainNetwork     // Network management
}

NodeJS SDK Installation

npm install @openweb3-io/wallet
# or
yarn add @openweb3-io/wallet

NodeJS SDK Initialization

import { ApiClient } from "@openweb3-io/wallet";

const apiKey = "YOUR_API_KEY";
const secret = "YOUR_SECRET";

const client = new ApiClient(apiKey, secret);

// Client contains the following services:
// - client.wallets          // Wallet management
// - client.addresses         // Address management
// - client.currencies        // Currency management
// - client.rates             // Rate service
// - client.transactions      // Transaction management
// - client.webhookEndpoints  // Webhook endpoint management
// - client.webhookEventTypes // Webhook event types
// - client.webhookEvents     // Webhook events
// - client.chainNetworks     // Network management

Wallet Management

Create Wallet

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func createWallet() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Wallet.Create(ctx, &wallet.CreateWalletIn{
        Name: "Test Wallet",
        Uid:  "user_123",
    })
    if err != nil {
        fmt.Println("Failed to create wallet:", err)
        return
    }
    fmt.Printf("Wallet ID: %s\n", result.Id)
}

NodeJS:

const result = await client.wallets.create({
    name: "Test Wallet",
    uid: "user_123",
});
console.log("Wallet ID:", result.id);

Get Wallet

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func getWallet() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Wallet.Retrieve(ctx, "wallet_abc123")
    if err != nil {
        fmt.Println("Failed to get wallet:", err)
        return
    }
    fmt.Printf("Wallet info: %+v\n", result)
}

NodeJS:

const result = await client.wallets.retrieve("wallet_abc123");
console.log("Wallet info:", result);

List Wallets

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listWallets() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Wallet.List(ctx, &wallet.ListWalletOptions{
        Limit: 20,
    })
    if err != nil {
        fmt.Println("Failed to list wallets:", err)
        return
    }
    for _, w := range result.Items {
        fmt.Printf("Wallet: %s - %s\n", w.Id, w.Name)
    }
}

NodeJS:

const result = await client.wallets.list({ limit: 20 });
result.items.forEach(w => {
    console.log(`Wallet: ${w.id} - ${w.name}`);
});

Update Wallet

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func updateWallet() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Wallet.Update(ctx, "wallet_abc123", &wallet.UpdateWalletIn{
        Name: "New Wallet Name",
    })
    if err != nil {
        fmt.Println("Failed to update wallet:", err)
        return
    }
    fmt.Printf("Wallet updated: %s\n", result.Name)
}

NodeJS:

const result = await client.wallets.update("wallet_abc123", {
    name: "New Wallet Name",
});
console.log("Wallet updated:", result.name);

Deposit Address Management

Get Deposit Address

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func getDepositAddress() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Address.GetDepositAddress(ctx, "wallet_abc123", &wallet.GetDepositAddressOptions{
        Currency: "USDT",
        Network: "trc20",
    })
    if err != nil {
        fmt.Println("Failed to get deposit address:", err)
        return
    }
    fmt.Printf("Deposit address: %s\n", result.Address)
}

NodeJS:

const result = await client.addresses.getDepositAddress({
    walletId: "wallet_abc123",
    currency: "USDT",
    network: "trc20",
});
console.log("Deposit address:", result.address);

List Deposit Addresses

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listDepositAddresses() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Address.ListDepositAddresses(ctx, "wallet_abc123", &wallet.ListDepositAddressesOptions{
        Limit:    20,
        Currency: "USDT",
    })
    if err != nil {
        fmt.Println("Failed to list deposit addresses:", err)
        return
    }
    for _, addr := range result.Items {
        fmt.Printf("Address: %s\n", addr.Address)
    }
}

NodeJS:

const result = await client.addresses.listDepositAddresses({
    walletId: "wallet_abc123",
    limit: 20,
    currency: "USDT",
});
result.items.forEach(addr => {
    console.log(`Address: ${addr.address}`);
});

Currency and Network

List Currencies

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listCurrencies() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Currency.List(ctx, &wallet.ListCurrencyOptions{
        Limit: 100,
    })
    if err != nil {
        fmt.Println("Failed to list currencies:", err)
        return
    }
    for _, c := range result.Items {
        fmt.Printf("Currency: %s (%s)\n", c.Name, c.Code)
    }
}

NodeJS:

const result = await client.currencies.list({ limit: 100 });
result.items.forEach(c => {
    console.log(`Currency: ${c.name} (${c.code})`);
});

Get Currency Details

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func getCurrency() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Currency.FindByCode(ctx, "USDT")
    if err != nil {
        fmt.Println("Failed to get currency:", err)
        return
    }
    fmt.Printf("Currency info: %+v\n", result)
}

NodeJS:

const result = await client.currencies.findByCode("USDT");
console.log("Currency info:", result);

List Networks

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listNetworks() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.ChainNetwork.List(ctx, &wallet.ListChainNetworkOptions{
        Limit: 100,
    })
    if err != nil {
        fmt.Println("Failed to list networks:", err)
        return
    }
    for _, n := range result.Items {
        fmt.Printf("Network: %s\n", n.Name)
    }
}

NodeJS:

const result = await client.chainNetworks.list({ limit: 100 });
result.items.forEach(n => {
    console.log(`Network: ${n.name}`);
});

Rate Service

Batch Get Rates

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func getRates() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Rate.GetRates(ctx, &wallet.GetRatesIn{
        Pairs: []wallet.CurrencyPair{
            {BaseCurrency: "USD", ToCurrency: "CNY"},
            {BaseCurrency: "USD", ToCurrency: "EUR"},
        },
    })
    if err != nil {
        fmt.Println("Failed to get rates:", err)
        return
    }
    for _, rate := range result.Rates {
        fmt.Printf("Rate: 1 %s = %s %s\n", rate.BaseCurrency, rate.Rate, rate.ToCurrency)
    }
}

NodeJS:

const result = await client.rates.getRates({
    pairs: [
        { baseCurrency: "USD", toCurrency: "CNY" },
        { baseCurrency: "USD", toCurrency: "EUR" },
    ],
});
result.rates.forEach(rate => {
    console.log(`Rate: 1 ${rate.baseCurrency} = ${rate.rate} ${rate.toCurrency}`);
});

Estimate Rate

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func estimateRate() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Rate.Estimate(ctx, &wallet.EstimateOptions{
        BaseCurrency: "USD",
        BaseAmount:   "100",
        ToCurrency:   "CNY",
    })
    if err != nil {
        fmt.Println("Failed to estimate rate:", err)
        return
    }
    fmt.Printf("Estimate: 100 USD = %s CNY\n", result.ToAmount)
}

NodeJS:

const result = await client.rates.estimate({
    baseCurrency: "USD",
    baseAmount: "100",
    toCurrency: "CNY",
});
console.log(`Estimate: 100 USD = ${result.toAmount} CNY`);

Transaction Management

Withdraw

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func withdraw() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Transaction.Withdraw(ctx, &wallet.WithdrawIn{
        WalletId:  "wallet_abc123",
        Currency:  "USDT",
        Network:   "trc20",
        Amount:    "1000000", // 1 USDT (6 decimals)
        ToAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    })
    if err != nil {
        fmt.Println("Withdrawal failed:", err)
        return
    }
    fmt.Printf("Transaction ID: %s\n", result.TransactionId)
}

NodeJS:

const result = await client.transactions.withdraw({
    walletId: "wallet_abc123",
    currency: "USDT",
    network: "trc20",
    amount: "1000000", // 1 USDT
    toAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
});
console.log("Transaction ID:", result.transactionId);

Estimate Withdrawal Fee

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func estimateFee() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Transaction.EstimateFee(ctx, &wallet.EstimateFeeIn{
        WalletId:  "wallet_abc123",
        Currency:  "USDT",
        Network:   "trc20",
        Amount:    "1000000",
        ToAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    })
    if err != nil {
        fmt.Println("Failed to estimate fee:", err)
        return
    }
    fmt.Printf("Fee: %s %s\n", result.FeeAmount, result.FeeCurrency)
}

NodeJS:

const result = await client.transactions.estimateFee({
    walletId: "wallet_abc123",
    currency: "USDT",
    network: "trc20",
    amount: "1000000",
    toAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
});
console.log(`Fee: ${result.feeAmount} ${result.feeCurrency}`);

Internal Transfer

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func transfer() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Transaction.Transfer(ctx, &wallet.TransferIn{
        From:     "wallet_abc123",
        To:       "wallet_def456",
        Currency: "USDT",
        Amount:   "1000000", // 1 USDT
    })
    if err != nil {
        fmt.Println("Transfer failed:", err)
        return
    }
    fmt.Printf("Transfer ID: %s\n", result.TransferId)
}

NodeJS:

const result = await client.transactions.transfer({
    from: "wallet_abc123",
    to: "wallet_def456",
    currency: "USDT",
    amount: "1000000",
});
console.log("Transfer ID:", result.transferId);

List Transactions

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listTransactions() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Transaction.List(ctx, &wallet.ListTransactionOptions{
        Limit: 20,
    })
    if err != nil {
        fmt.Println("Failed to list transactions:", err)
        return
    }
    for _, tx := range result.Items {
        fmt.Printf("Transaction: %s - %s %s\n", tx.Id, tx.Amount, tx.Currency)
    }
}

NodeJS:

const result = await client.transactions.list({ limit: 20 });
result.items.forEach(tx => {
    console.log(`Transaction: ${tx.id} - ${tx.amount} ${tx.currency}`);
});

Get Transaction Details

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func getTransaction() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.Transaction.Retrieve(ctx, "tx_abc123")
    if err != nil {
        fmt.Println("Failed to get transaction:", err)
        return
    }
    fmt.Printf("Transaction info: %+v\n", result)
}

NodeJS:

const result = await client.transactions.retrieve("tx_abc123");
console.log("Transaction info:", result);

Webhook Management

Create Webhook Endpoint

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func createWebhookEndpoint() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.WebhookEndpoint.Create(ctx, &wallet.CreateEndpointIn{
        Url:         "https://your-server.com/webhook",
        Description: "Production callback",
        FilterTypes: []string{"deposit_succeed", "withdraw_succeed"},
    })
    if err != nil {
        fmt.Println("Failed to create webhook endpoint:", err)
        return
    }
    fmt.Printf("Endpoint ID: %s\n", result.Id)
}

NodeJS:

const result = await client.webhookEndpoints.create({
    url: "https://your-server.com/webhook",
    description: "Production callback",
    filterTypes: ["deposit_succeed", "withdraw_succeed"],
});
console.log("Endpoint ID:", result.id);

Get Webhook Endpoint

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func getWebhookEndpoint() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.WebhookEndpoint.Retrieve(ctx, "endpoint_abc123")
    if err != nil {
        fmt.Println("Failed to get webhook endpoint:", err)
        return
    }
    fmt.Printf("Endpoint info: %+v\n", result)
}

NodeJS:

const result = await client.webhookEndpoints.retrieve("endpoint_abc123");
console.log("Endpoint info:", result);

Update Webhook Endpoint

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func updateWebhookEndpoint() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.WebhookEndpoint.Update(ctx, "endpoint_abc123", &wallet.UpdateEndpointIn{
        Description: "Updated description",
    })
    if err != nil {
        fmt.Println("Failed to update webhook endpoint:", err)
        return
    }
    fmt.Printf("Endpoint updated: %s\n", result.Id)
}

NodeJS:

const result = await client.webhookEndpoints.update("endpoint_abc123", {
    description: "Updated description",
});
console.log("Endpoint updated:", result.id);

Delete Webhook Endpoint

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func deleteWebhookEndpoint() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    err := client.WebhookEndpoint.Delete(ctx, "endpoint_abc123")
    if err != nil {
        fmt.Println("Failed to delete webhook endpoint:", err)
        return
    }
    fmt.Println("Endpoint deleted")
}

NodeJS:

await client.webhookEndpoints.delete("endpoint_abc123");
console.log("Endpoint deleted");

List Webhook Endpoints

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listWebhookEndpoints() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.WebhookEndpoint.List(ctx, &wallet.ListWebhookOptions{
        Limit: 20,
    })
    if err != nil {
        fmt.Println("Failed to list webhook endpoints:", err)
        return
    }
    for _, ep := range result.Items {
        fmt.Printf("Endpoint: %s - %s\n", ep.Id, ep.Url)
    }
}

NodeJS:

const result = await client.webhookEndpoints.list({ limit: 20 });
result.items.forEach(ep => {
    console.log(`Endpoint: ${ep.id} - ${ep.url}`);
});

List Webhook Event Types

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func listWebhookEventTypes() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    result, err := client.WebhookEventTypes.List(ctx)
    if err != nil {
        fmt.Println("Failed to list event types:", err)
        return
    }
    for _, t := range result {
        fmt.Printf("Event type: %s\n", t)
    }
}

NodeJS:

const result = await client.webhookEventTypes.list();
result.forEach(t => {
    console.log(`Event type: ${t}`);
});

Resend Webhook Event

Golang:

import (
    "context"
    "fmt"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func resendWebhookEvent() {
    client := wallet.New(&wallet.APIClientOptions{
        ApiKey: "YOUR_API_KEY",
        Secret: "YOUR_SECRET",
    })

    ctx := context.Background()
    _, err := client.WebhookEvents.Resend(ctx, &wallet.ResendEventIn{
        EventId: "event_abc123",
    })
    if err != nil {
        fmt.Println("Failed to resend event:", err)
        return
    }
    fmt.Println("Event resent")
}

NodeJS:

await client.webhookEvents.resend({
    eventId: "event_abc123",
});
console.log("Event resent");

Webhook Events

Supported Event Types

deposit_succeed - Deposit success
withdraw_succeed - Withdrawal success
withdraw_failed - Withdrawal failed
withdraw_approved - Withdrawal approved
transfer_succeed - Transfer success
transfer_failed - Transfer failed
transfer_approved - Transfer approved

Event Structure

{
    "eventType": "deposit_succeed",
    "payload": {
        "transactionId": "92841860-481e-4ba4-9be2-12b1e497facf",
        "type": "IN",
        "walletId": "wallet_abc123",
        "gateway": "deposit",
        "amount": {
            "currency": "USDT",
            "amount": "100.00"
        },
        "status": "SUCCEED",
        "createdAt": "2024-02-14T12:00:00Z"
    }
}

Callback Handling

Callback handling mainly consists of 3 parts:

Verify signature
Event deduplication
Process event

Golang

import (
    "context"
    "fmt"
    "net/http"

    wallet "github.com/openweb3-io/wallet-openapi/go"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // 1. Read request body
    body := make([]byte, r.ContentLength)
    r.Read(body)

    // 2. Get signature header
    signature := r.Header.Get("X-Signature")

    // 3. Verify signature
    publicKey := "YOUR_PUBLIC_KEY_IN PEM FORMAT"
    client, err := wallet.NewWebhookClient(publicKey)
    if err != nil {
        fmt.Println("Failed to create webhook client:", err)
        w.WriteHeader(http.StatusInternalServerError)
        return
    }

    err = client.Verify(body, signature)
    if err != nil {
        fmt.Println("Signature verification failed:", err)
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    // 4. Process event
    fmt.Println("Received callback event:", string(body))
    w.WriteHeader(http.StatusOK)
}

NodeJS

import { WebhookClient } from "@openweb3-io/wallet";

const publicKey = `-----BEGIN PUBLIC KEY-----
YOUR PUBLIC KEY IN PEM FORMAT
-----END PUBLIC KEY-----`;

const webhookClient = new WebhookClient(publicKey);

async function webhookHandler(req, res) {
    const { body, headers } = req;
    const signature = headers["x-signature"];

    // Verify signature
    const isValid = await webhookClient.verify(body, signature);

    if (!isValid) {
        console.log("Signature verification failed");
        res.status(401).send("Invalid signature");
        return;
    }

    // Process event
    const event = JSON.parse(body);
    console.log("Received callback event:", event.eventType);

    res.status(200).send("OK");
}

Signature Verification

Webhook callbacks use RSA-SHA256 algorithm for signature verification, which is different from the request signing that uses ED25519.

Verification process:

Extract X-Signature from Header
Get the original request body
Verify signature using PEM format public key

Obtain Public Key: Login to Dashboard -> Settings -> Developer to get the public key