Authentication and Conventions

Developer API endpoints are API-key guarded REST mappings over Swig backend services.

Base URL

Examples use:

https://api.onswig.com

Use the environment-specific base URL provided for your project when working against dev, staging, or private deployments.

Authentication

Send your API key as a bearer token:

Authorization: Bearer sk_your_api_key

Runtime API keys are created in the Developer Portal.

API keys are server-only credentials. Do not ship one to a browser or mobile bundle, and do not expose one through a public build-time variable such as NEXT_PUBLIC_*. Route browser and mobile traffic through your own backend, or use the Developer SDK server route adapters, which keep the key server-side for you.

The gateway also accepts x-api-key, but bearer auth is the documented and SDK-default form. This section covers runtime product APIs. Use the Developer Portal for administrative operations.

Retry safety

Treat the two request classes differently:

Request	Safe to retry
`GET`	yes — reads are idempotent
`POST`	not by default — a replay can duplicate work
`POST /paymaster/sponsor`, `POST /paymaster/sponsor/bundle`	yes, when you send the same idempotency key

Sponsorship is the one write where a retry is explicitly safe, because a matching idempotency key returns the original response instead of spending again. Derive that key from something stable in your own domain, such as an order id, rather than generating a new value per attempt. The Developer SDKs encode exactly this policy: GET requests use the configured retry policy, POST requests do not retry, and sponsorship retries only when an idempotency key is present.

JSON encoding

The REST API uses protobuf JSON mapping.

Protobuf type	JSON form
`string`, `bool`, `double`	ordinary JSON string, boolean, or number
`uint64`, `int64`	string or number depending on field and client encoder; use strings for large values when in doubt
`bytes`	base64 string
enum fields	enum names such as `NETWORK_DEVNET`, unless a field explicitly documents a legacy string
`google.protobuf.Struct`	JSON object

Request mapping

Fields in the path template go in the URL. Remaining scalar fields on GET requests become query parameters.

curl "https://api.onswig.com/wallet/swig/ExampleConfig/token-transactions?network=NETWORK_DEVNET&limit=25" \
  -H "Authorization: Bearer sk_your_api_key"

For POST, PUT, and PATCH endpoints, the request body is the full request message unless noted otherwise.

curl "https://api.onswig.com/transaction/transfer/sol" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "NETWORK_DEVNET",
    "feePayer": "FeePayerPublicKey",
    "swigAddress": "SwigConfigAddress",
    "requesterAuthority": {
      "ed25519": { "publicKey": "RequesterPublicKey" }
    },
    "destination": "DestinationPublicKey",
    "lamports": "1000000"
  }'

Field casing

The protobuf field names are snake_case. JSON transcoding accepts protobuf JSON names, which are normally camelCase. This docs section uses camelCase in JSON examples and snake_case in endpoint tables when referring to the source proto field.

Response shape

Successful responses are JSON encodings of the protobuf response message. API errors are returned by the gateway or service as HTTP errors with a gRPC status mapping. See Errors.

Start Here

Runtime APIs

Boundaries

Authentication and Conventions

Base URL

Authentication

Retry safety

JSON encoding

Request mapping

Field casing

Response shape

​Base URL

​Authentication

​Retry safety

​JSON encoding

​Request mapping

​Field casing

​Response shape

Base URL

Authentication

Retry safety

JSON encoding

Request mapping

Field casing

Response shape