Developer

Integration API Specification.

Back to Home

Developer

VGO DeFi Payment Service

Integration API Specification

Version: 1.0 Environment: Production

Base URL: https://api.vgo.world/pay/v1

This API allows developers to integrate TXC payments with balance check, transfer, and transaction history only.

1️⃣

Overview

The VGO Minimal DeFi Payment API enables:

TXC Wallet Balance Retrieval
TXC Transfer (Peer-to-Peer / Merchant)
Transaction History Retrieval
Transfer Status Confirmation

This API does not expose:

Dividend logic
Mining reward logic
Internal ledger architecture
Equity movement

All transactions are internally validated on the decentralized ledger but external apps interact only with this clean payment layer.

2️⃣

Authentication

2.1 Authentication Method

All API calls require:

Authorization: Bearer <JWT_TOKEN>

Tokens are issued via secure partner onboarding.

2.2 Headers Required

Header	Required	Description
`Authorization: Bearer <token>`	Yes	JWT authentication token
`Content-Type: application/json`	Yes	JSON content type
`Idempotency-Key: <unique_key>`	Yes*	Required for transfers only

3️⃣

Wallet API

3.1 Get Wallet Balance

GET /wallet/balance

Response

{
      "wallet_id": "WALLET123",
      "currency": "TXC",
      "available_balance": 1250.75,
      "pending_balance": 50.00,
      "last_updated": "2026-02-11T10:00:00Z"
    }

Field	Description
`wallet_id`	Unique wallet identifier
`available_balance`	Spendable TXC
`pending_balance`	TXC awaiting confirmation
`last_updated`	Timestamp

4️⃣

TXC Transfer API

4.1 Initiate Transfer

POST /transfer

Headers

Authorization: Bearer <token>
Idempotency-Key: UNIQUE-ORDER-ID-123

Request Body

{
      "recipient_wallet_id": "WALLET999",
      "amount": 150.00,
      "reference_id": "ORDER-1024",
      "note": "Payment for services"
    }

Field	Required	Description
`recipient_wallet_id`	Yes	Destination wallet
`amount`	Yes	TXC amount
`reference_id`	Yes	Merchant reference
`note`	No	Optional memo

4.2 Transfer Response (Processing)

{
      "transaction_id": "TX2001",
      "status": "processing",
      "created_at": "2026-02-11T10:05:00Z"
    }

4.3 Transfer Status (Confirmed)

{
      "transaction_id": "TX2001",
      "status": "confirmed",
      "ledger_reference": "0xHASH9876",
      "confirmed_at": "2026-02-11T10:06:10Z"
    }

4.4 Transfer Status Values

processing Awaiting ledger validation

confirmed Successfully validated

failed Transaction rejected

reversed Transaction reversed

5️⃣

Transaction History API

5.1 Get Transactions

GET /transactions?limit=20&cursor=abc123

Response

{
      "transactions": [
        {
          "transaction_id": "TX2001",
          "type": "transfer",
          "direction": "debit",
          "amount": 150.00,
          "status": "confirmed",
          "reference_id": "ORDER-1024",
          "created_at": "2026-02-11T10:05:00Z"
        }
      ],
      "next_cursor": "def456"
    }

5.2 Transaction Fields

Field	Description
`type`	transfer
`direction`	debit / credit
`amount`	TXC value
`status`	processing / confirmed
`reference_id`	Merchant reference
`next_cursor`	Pagination token

6️⃣

Transfer Status Lookup API

6.1 Check Transaction Status

GET /transfer/{transaction_id}

Response

{
      "transaction_id": "TX2001",
      "status": "confirmed",
      "amount": 150.00,
      "recipient_wallet_id": "WALLET999",
      "ledger_reference": "0xHASH9876"
    }

7️⃣

Webhook Notifications

To receive real-time confirmation updates.

7.1 Register Webhook

POST /webhook/register

{
      "url": "https://merchant.com/webhook",
      "event": "transfer.confirmed"
    }

7.2 Webhook Payload Example

{
      "event": "transfer.confirmed",
      "transaction_id": "TX2001",
      "amount": 150.00,
      "status": "confirmed"
    }

8️⃣

Idempotency

To prevent duplicate transfers:

Each transfer request must include: Idempotency-Key: unique-value
If duplicate key is submitted: API returns original transaction response
No duplicate payment processed

9️⃣

Error Handling

Standard HTTP Codes

200 Success

400 Invalid request

401 Unauthorized

403 Forbidden

404 Not found

409 Duplicate idempotency key

422 Insufficient balance

429 Rate limit exceeded

500 Server error

Example Error Response

{
      "error": {
        "code": "INSUFFICIENT_BALANCE",
        "message": "Not enough TXC available"
      }
    }

🔐

Security Requirements

HTTPS only
JWT authentication
Idempotency key mandatory for transfers
Rate limit: 100 requests per minute
HMAC signature required for high-value transactions (optional tier)
IP allowlisting for production partners

🔄

Transaction Lifecycle

📤

Client Initiates Transfer

↓

✅

API Accepts Request

↓

⏳

Processing Status

↓

🔗

Ledger Validation (Internal)

↓

✅

Confirmed

↓

🔔

Webhook Sent

📋

Integration Summary

Developers integrating VGO Minimal DeFi API can:

Show TXC balance
Send TXC payments
Track transactions
Receive confirmation callbacks

Everything else (ledger, mining, dividend) is handled internally by VGO.

Final Notes

TXC is the only supported currency in this API.
Fiat conversion must be handled separately via Bridge Agent APIs.
This API is optimized for:
- Mobile apps
- E-commerce platforms
- SaaS integrations
- Wallet integrations