Skip to main content
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

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

EndpointMethodDescription
/v1/sponsorPOSTWrap and submit a transaction.
/v1/simulatePOSTSimulate a Soroban transaction.
/v1/estimatePOSTGet fee estimates for a transaction.
/healthGETCheck 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