REST API

Integrate Grat from any language using standard HTTP requests.

Grat’s relay is a standard REST API. Any programming language that can make HTTP requests can integrate directly with Grat. No dedicated SDK is required to start sponsoring transactions.

Sponsoring a Transaction

To sponsor a transaction, send a POST request to the /v1/sponsor endpoint with the base64-encoded XDR.

curl -X POST http://localhost:3000/v1/sponsor \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": "AAAAAgAAAA...",
    "network": "testnet"
  }'

Language Examples

Python

import requests

def sponsor_tx(xdr):
    url = "http://localhost:3000/v1/sponsor"
    payload = {
        "transaction": xdr,
        "network": "testnet"
    }
    response = requests.post(url, json=payload)
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}")
        return None

Endpoints Summary

Endpoint	Method	Description
/v1/sponsor	POST	Wrap and submit a transaction.
/v1/simulate	POST	Simulate a Soroban transaction.
/v1/estimate	POST	Get fee estimates for a transaction.
/health	GET	Check relay health and status.

Error Handling

When an error occurs, the API returns a JSON object with a standardized format.

{
  "error": {
    "code": "SUBMISSION_FAILED",
    "message": "Transaction Failed: tx_bad_seq",
    "details": { "result_codes": { "transaction": "tx_bad_seq" } },
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Retry Logic

If you are implementing your own integration, we recommend retrying requests that return the following status codes:

• 429 Too Many Requests: Use the value in the Retry-After header.
• 503 Service Unavailable: Use exponential backoff (e.g., 1s, 2s, 4s).

Tips

• Idempotency: Use the X-Idempotency-Key header to safely retry requests without risk of double-submission.
• Rate Limits: Pay attention to rate limit headers in the response to avoid 429 errors.
• Stroops: All fee values in the API are represented in stroops (1 XLM = 10,000,000 stroops).

Do you need a dedicated SDK for your programming language? Open a feature request on our GitHub repository.

View on GitHub