API Documentation

Integrate the GCNhub API to bridge digital assets to 10,000+ retail brands. RESTful endpoints, SDKs, and webhooks for real-time updates.

The GCNhub API is in private beta. The endpoints below describe the integration as it ships today. Base URLs, credentials and the client library are issued on approval — request access and our team will send your sandbox details.

Quick Start

Once your access is approved you receive a sandbox base URL, an API key and the client library for your stack. From there, a first successful call takes about a minute.

first request

export BASE_URL="<the base URL we send you>"
export GCNHUB_API_KEY="<your sandbox key>"

curl -X GET $BASE_URL/v1/brands \
  -H "Authorization: Bearer $GCNHUB_API_KEY"

Authentication

All API requests must include your API key in the Authorization header. Keys are scoped per environment (sandbox vs. production). Never expose your production key in client-side code.

Authorization header

Authorization: Bearer YOUR_API_KEY

Access and base URL

Sandbox and production base URLs are issued per integration when your access is approved, along with your API keys. Every example on this page uses $BASE_URL in place of the host you are assigned.

Endpoints

GET/v1/brands

Retrieve a list of available brands in a given region, filtered by category.

cURL

curl -X GET $BASE_URL/v1/brands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d region=US \
  -d category=retail

# Response
{
  "data": [
    { "id": "amazon", "name": "Amazon", "regions": ["US","UK","DE"] },
    { "id": "starbucks", "name": "Starbucks", "regions": ["US","CA","UK"] }
  ],
  "total": 10234
}

POST/v1/orders

Create a gift card order. The payment is settled in crypto and the gift card is returned upon confirmation.

cURL

curl -X POST $BASE_URL/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "amazon",
    "amount": 50,
    "currency": "USD",
    "wallet": "0x...",
    "webhook_url": "https://yourapp.com/webhooks/gcnhub"
  }'

# Response
{
  "order_id": "ord_a1b2c3",
  "status": "pending",
  "amount": 50,
  "currency": "USD",
  "brand": "amazon"
}

GET/v1/orders/{order_id}

Retrieve the status and details of a specific order.

cURL

curl -X GET $BASE_URL/v1/orders/ord_a1b2c3 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "order_id": "ord_a1b2c3",
  "status": "completed",
  "gift_card": {
    "code": "ABCD-1234-EFGH",
    "pin": "5678",
    "amount": 50,
    "currency": "USD",
    "expires": "2027-12-31"
  }
}

POST/v1/webhooks

cURL

curl -X POST $BASE_URL/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/gcnhub",
    "events": ["order.completed", "order.failed"]
  }'

SDK Example

The JavaScript client handles authentication, retries, and response parsing for you. It is distributed with your credentials rather than from a public registry.

integration.js

// The GCNhub client is issued with your API access.
const hub = new GCNhub({
  apiKey: process.env.GCNHUB_API_KEY
});

// Fetch available brands
const brands = await hub.catalog.getBrands({ region: 'US' });

// Create a gift card order
const order = await hub.orders.create({
  brand: 'amazon',
  amount: 50,
  currency: 'USD',
  wallet: userWalletAddress
});

console.log(order.order_id); // "ord_a1b2c3"

SDKs are also available for Python, Go, and Ruby.

Webhooks

Subscribe to real-time events so your platform can react instantly when an order completes or fails. Webhook payloads are signed with HMAC-SHA256 — verify the signature on every request.

Webhook payload

{
  "event": "order.completed",
  "order_id": "ord_a1b2c3",
  "brand": "amazon",
  "amount": 50,
  "currency": "USD",
  "gift_card": { "code": "ABCD-1234-EFGH", "pin": "5678" },
  "timestamp": "2026-07-24T10:30:00Z"
}

Rate Limiting

Requests are rate-limited per API key. Standard tier allows 60 requests per minute; Enterprise tier is custom. Rate limit headers are included in every response.

X-RateLimit-Limit:60

X-RateLimit-Remaining:42

X-RateLimit-Reset:1721820600

Error Codes

200Success — the request was processed correctly.

400Bad Request — missing or invalid parameters.

401Unauthorized — missing or invalid API key.

404Not Found — the requested resource does not exist.

429Too Many Requests — rate limit exceeded.

500Server Error — something went wrong on our end.

Ready to build?

Request API access and our team will get you set up with sandbox credentials within 24 hours.

Get API Access