Skip to main content

Introduction to GStable API

Welcome to the GStable API.

GStable API is designed to provide developers with a stable and efficient payment infrastructure built on blockchain. Through our API, you can create Payment Links, manage Checkout Sessions, and leverage stablecoin networks to enable global payments.

To lower the integration barrier, our API adopts engineering-focused design principles, providing unified interaction patterns and predictable response structures to help you complete integration quickly.

Protocol & Design​

1. HTTP Methods​

To simplify call logic, the API uses only two HTTP methods:

  • GET: Used to retrieve resources (e.g., query order details, get webhook lists).
  • POST: Used to create or update resources, or perform operations (e.g., create payment links, archive products).

2. Base URL​

All API requests are sent via HTTPS to the following base address:

https://api.gstable.io/payment/v1

3. Request Format​

  • The body of all POST requests must be in JSON format.
  • Please ensure Content-Type: application/json is set in the HTTP Header.

Response Format​

GStable API uses a unified JSON Envelope format to return data. Whether the request succeeds or fails (at the business logic level), the API will generally return this structure.

Unified Response Structure​

All interface responses always contain the following three fields:

{
  "code": 0,
  "message": "success",
  "data": {
    // Specific business data
    "id": "prod_example_item_01",
    "name": "Premium Plan"
  }
}
FieldTypeDescription
codeIntegerBusiness Status Code.
0 indicates successful execution.
Non-zero indicates a business error occurred (e.g., invalid parameters, insufficient balance).
messageStringMessage.
A human-readable string used for debugging or displaying the error reason to the user.
dataAnyResponse Data.
The main result of the API call. If code is not 0, this field is usually null.

HTTP Status Code Handling​

To simplify error handling logic, GStable API rarely uses error status codes at the HTTP level.

  • HTTP 200 OK: The vast majority of requests (including business logic errors like "missing parameters" or "object not found") will return a 200 status code. Please be sure to check the code field in the response Body to determine if the business operation was successful.
  • HTTP 401 Unauthorized: Returned only when the API Key is missing or invalid, indicating authentication failure.
  • HTTP 429 Too Many Requests: Indicates that the request frequency has exceeded the rate limit quota.
Development Tip

When writing client code, it is recommended to first check if the HTTP status code is 200. If it is, then parse the JSON and check if code === 0 holds true.

Core Business Mechanisms​

Understanding GStable's payment confirmation and settlement mechanisms will help you better handle order states:

1. Payment Confirmation​

GStable greatly simplifies the complexity of blockchain payments. We adopt a logic where on-chain payment success is considered order completion.

  • Payment Determination: The system monitors the blockchain network in real-time. Once the payer's on-chain transaction is detected as successful, GStable will immediately mark the order status as paid.
  • Deterministic Settlement: GStable provides deterministic settlement, ensuring funds reach the merchant's wallet. Even if subsequent cross-chain routing takes some time (usually 30-40 seconds), this is part of the underlying protocol's automatic routing process and does not affect the order status determination on the merchant side.
  • User Experience: Payers do not need to wait for funds to finally settle into the merchant's wallet; they only need to confirm their transfer transaction is successful to leave the page.

2. Asset & Payment Decoupling​

GStable implements the separation of the payment layer and the settlement layer, supporting "Pay with Any Token, Settle in Specified Asset".

  • Merchant Side: When creating a Product or Checkout Session, you can specify the pricing currency (e.g., USDC on Arbitrum).
  • User Side: When paying, users can use any token on any chain supported by GStable (e.g., USDT on Ethereum).
  • Automatic Routing: The system automatically handles cross-chain routing and exchange. Merchants do not need to care about what asset the user holds, only the asset that is finally settled.

3. Non-Custodial Security​

GStable adheres to non-custodial principles, providing the highest level of fund security for merchants and users.

  • No Capital Pool: The platform does not establish an intermediate capital pool; fund flows are executed entirely based on on-chain smart contracts.
  • Peer-to-Peer Settlement: Funds flow directly from the user's wallet to the merchant's self-custodial wallet and do not remain on the platform.
  • Zero Private Key Risk: The platform does not touch or hold any private keys from the user side or the merchant side.

Core Resources Overview​

GStable API is built around the following core resources:

ResourceDescriptionPath
ProductDefines a product or service (name, price, image)./product/*
Payment LinkA permanent payment link generated based on a product, suitable for no-code scenarios./payment/link/*
Checkout SessionA temporary checkout session generated programmatically, suitable for low-code integration./session/*
WebhookUsed to receive asynchronous payment result notifications./webhook/*
AccountUsed to query collection accounts and wallets configured in the platform./account/*

Limits & Quotas​

  • Default Rate Limit: API requests are limited to 100 requests per second (QPS). Exceeding the limit will return HTTP 429.
  • Pagination: List interfaces (such as /product/list) support pagination queries.