Skip to main content
The G2C Platform API provides comprehensive functionality for managing digital assets with blockchain-based traceability. The API follows RESTful principles and is organized around core resources: wallets, tokens, categories, objects, and files.

​
Base URL

https://api.g2cplatform.com/v2

​
Authentication

G2C Platform supports two authentication methods:

​
API Key Authentication

For server-to-server communication: 
X-API-Key: your_api_key_here

​
JWT Bearer Authentication

For wallet-based operations: 
Authorization: Bearer your_jwt_token_here

​
Core Resources

​
System Health

Monitor API and authentication system status:
EndpointMethodDescriptionAuth Required
/healthGETCheck overall API health❌
/auth/healthGETCheck authentication system health✅

​
Wallet Management

Create and manage digital identities:
EndpointMethodDescriptionAuth Required
/walletsGETList wallets✅ API Key
/walletsPOSTCreate new wallet✅ API Key
/wallets/{walletId}GETGet wallet details✅ API Key
/wallets/{walletId}PUTUpdate wallet✅ API Key
/wallets/{walletId}DELETEDelete wallet✅ API Key

​
Wallet Authentication

Authenticate wallets and manage sessions:
EndpointMethodDescriptionAuth Required
/auth/wallet/loginPOSTAuthenticate wallet❌
/auth/wallet/logoutPOSTInvalidate JWT token✅ JWT
/auth/wallet/refreshPOSTRefresh JWT token✅ JWT
/auth/wallet/recoverPOSTRequest password recovery❌
/auth/wallet/resetPOSTReset wallet password❌

​
Token Management

Create, transfer, and track blockchain tokens:
EndpointMethodDescriptionAuth Required
/tokens/mintPOSTCreate new tokens (fungible/NFT)✅ API Key
/tokens/transferPOSTTransfer tokens between wallets✅ API Key
/tokens/{tokenId}GETGet token details✅ API Key
/tokensGETList tokens with filters✅ API Key
/tokens/historyGETGet token transaction history✅ API Key

​
Category Management

Organize digital objects hierarchically:
EndpointMethodDescriptionAuth Required
/categoriesGETList categories✅ API Key
/categoriesPOSTCreate new category✅ API Key
/categories/{categoryId}GETGet category details✅ API Key
/categories/{categoryId}PUTUpdate category✅ API Key
/categories/{categoryId}DELETEDelete category✅ API Key

​
Subcategory Management

Manage subcategories within categories:
EndpointMethodDescriptionAuth Required
/categories/{categoryId}/subcategoriesPOSTCreate subcategory✅ API Key
/categories/{categoryId}/subcategories/{subcategoryId}GETGet subcategory✅ API Key
/categories/{categoryId}/subcategories/{subcategoryId}PUTUpdate subcategory✅ API Key
/categories/{categoryId}/subcategories/{subcategoryId}DELETEDelete subcategory✅ API Key

​
Object Management

Track digital objects with blockchain audit trails:
EndpointMethodDescriptionAuth Required
/categories/{categoryId}/subcategories/{subcategoryId}/objectsGETList objects in subcategory✅ API Key
/categories/{categoryId}/subcategories/{subcategoryId}/objectsPOSTCreate object✅ API Key
/objectsGETList all objects with filters✅ API Key
/objects/{objectId}GETGet object details✅ API Key
/objects/{objectId}PUTUpdate object✅ API Key
/objects/{objectId}DELETEDelete object✅ API Key

​
File Management

Handle file uploads and downloads:
EndpointMethodDescriptionAuth Required
/files/uploadPOSTUpload file✅ API Key
/files/{fileId}GETGet file details✅ API Key
/files/{fileId}DELETEDelete file✅ API Key

​
Hierarchical Structure

G2C Platform uses a clear hierarchical structure for organizing digital assets: 
Categories (categoryId)
├── Subcategories (subcategoryId)
│   └── Objects (objectId/externalId)
│       ├── Files
│       └── Blockchain Events
└── Metadata

Wallets (walletId)
├── Tokens (tokenId)
│   ├── Fungible Tokens (symbol, amount)
│   └── NFTs (metadata, attributes)
└── Transaction History

​
Token Types

​
Fungible Tokens

Interchangeable digital assets:
  • Digital currencies
  • Loyalty points
  • Credits or rewards
  • Represented by symbol and amount

​
Non-Fungible Tokens (NFTs)

Unique digital assets:
  • Digital certificates
  • Unique collectibles
  • Identity tokens
  • Represented by unique metadata

​
Request/Response Patterns

​
Content Types

  • JSON Requests: application/json
  • File Uploads: multipart/form-data

​
Standard Response Format

​
Success Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Resource Name",
  "status": "active",
  "createdAt": "2024-03-15T10:30:00Z",
  "updatedAt": "2024-03-15T10:30:00Z"
}

​
List Response with Pagination

{
  "data": [
    // Array of resources
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "hasNext": true,
    "hasPrevious": false
  }
}

​
Error Response

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "timestamp": "2024-03-15T10:30:00Z",
  "path": "/api/endpoint",
  "requestId": "req_abc123def456"
}

​
Pagination

List endpoints support consistent pagination:
ParameterTypeDefaultDescription
limitinteger20Items per page (max 100)
offsetinteger0Items to skip
sortstringcreatedAt:descSort field and direction

​
Example Paginated Request

curl -X GET "https://api.g2cplatform.com/v2/tokens?limit=50&offset=100&tokenType=nft" \
  -H "X-API-Key: your-api-key"

​
HTTP Status Codes

Status CodeDescriptionCommon Usage
200OKSuccessful GET, PUT operations
201CreatedSuccessful POST operations
204No ContentSuccessful DELETE operations
400Bad RequestInvalid request data
401UnauthorizedMissing or invalid credentials
403ForbiddenInsufficient permissions
404Not FoundResource not found
409ConflictResource already exists
500Internal Server ErrorServer-side error

​
Blockchain Integration

​
BSV Blockchain

All token operations and object events are recorded on the BSV blockchain for:
  • Immutable audit trails
  • Cryptographic verification
  • Complete transaction history
  • Compliance and regulatory requirements

​
Blockchain Data

Responses include blockchain information: 
{
  "blockchain": {
    "txId": "abc123...def456",
    "lastTxId": "ghi789...jkl012",
    "confirmations": 6,
    "fee": 0.00001,
    "eventCount": 5
  }
}

​
Security Best Practices

​
API Key Security

  • Store keys in environment variables
  • Never expose keys in client-side code
  • Use different keys for different environments
  • Rotate keys regularly

​
JWT Token Security

  • Tokens expire after a set time
  • Use refresh tokens for extended sessions
  • Invalidate tokens on logout
  • Store securely on client side

​
Data Protection

  • All requests use HTTPS
  • Data is encrypted in transit and at rest
  • Access controls by wallet and API key
  • Audit trails for all operations

​
Common Use Cases

​
Digital Asset Management

  • Create categories for asset types
  • Mint NFTs for unique items
  • Track ownership with blockchain proof
  • Manage asset lifecycle events

​
Token Economy

  • Issue fungible tokens for rewards
  • Create NFT certificates
  • Track token transfers
  • Build loyalty programs

​
Supply Chain Traceability

  • Create objects for products
  • Record manufacturing steps
  • Track transfers between parties
  • Verify authenticity with blockchain

​
Error Handling

​
Validation Errors

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "amount",
    "message": "Must be greater than 0"
  }
}

​
Rate Limiting

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

​
Next Steps

Quick Start

Get started in under 5 minutes

Authentication Guide

Learn about API authentication

Token Management

Start with blockchain tokens

Wallet Creation

Create your first wallet