API Reference

The gateway exposes a REST API over HTTP. All endpoints require an API key passed as a header. All request and response bodies are JSON.

Authentication

Every request must include your API key:

http

X-API-KEY: your-api-key

Requests without a valid key return 401 Unauthorized. Rate limiting returns 429 Too Many Requests — the SDK handles retries automatically.

ℹ

NoteThe /health endpoint does not require authentication. Use it for uptime monitoring without exposing your API key.

Base URL

bash

https://gateway-production-7e9c.up.railway.app

All paths below are relative to this base.

Intents

POST/v1/intents

Submit a new encrypted intent to the gateway.

GET/v1/intents

List intents. Filter by user address, status, or batch ID.

GET/v1/intents/:intentId

Get the current status of a single intent.

POST/v1/intents/:intentId/cancel

Cancel an intent. Requires wallet signature.

POST/v1/intents/:intentId/onchain

Notify the gateway that a wallet transaction confirmed on-chain.

POST /v1/intents — request body

Field	Type	Description
`intent_id`*	`string`	Unique ID generated by IntentBuilder
`user_address`*	`string`	Starknet address of the user placing the order
`ciphertext`*	`string`	Hex-encoded AES-GCM encrypted intent payload
`encrypted_session_key`*	`string`	Session key encrypted with the gateway's public key
`client_public_key`*	`string`	Client's X25519 ephemeral public key (hex)
`commitment`*	`string`	Pedersen hash of the full intent — what goes on-chain
`user_signature`*	`string[]`	Starknet signature components from the user's wallet
`nonce`*	`string`	Random nonce used in intent hash and amount commitment
`authorization_hash`	`string`	Optional: hash the user explicitly authorised off-chain
`submission_mode`	`string`	'GATEWAY' (default) or 'SELF_COMMIT' — who submits the on-chain tx

POST /v1/intents — response

json

{
  "intent_id": "0x...",
  "batch_id": "0x...",
  "estimated_execution_time": 28,
  "awaiting_user_transaction": true
}

GET /v1/intents — query params

Param	Type	Description
`user_address`	`string`	Filter to a specific wallet address
`status`	`string`	pending \| committed \| in_batch \| settled \| failed \| cancelled \| expired
`batch_id`	`string`	Filter to intents in a specific batch
`limit`	`number`	Max results per page (default 20, max 100)
`offset`	`number`	Pagination offset

Batches

GET/v1/batches

List batch windows. Filter by status.

GET/v1/batches/:batchId

Get details of a single batch.

GET/v1/batches/:batchId/intents

List all intent IDs in a batch.

Batch object

json

{
  "batch_id": "0x...",
  "close_time": 1700000030,
  "intent_count": 4,
  "auction_deadline": 1700000050,
  "status": "settled",
  "created_at": "2024-01-01T00:00:00Z",
  "settled_at": "2024-01-01T00:00:55Z",
  "failure_reason": null,
  "failed_at": null
}

Gateway

GET/v1/gateway/public_key

Returns the gateway's current X25519 public key. Fetch this before encrypting an intent.

GET/health

Returns 200 if the gateway is up. No auth required.

GET /v1/gateway/public_key — response

json

{
  "gateway_public_key": "0x..."
}

Error format

All errors return a consistent JSON body:

json

{
  "error": "intent_not_found",
  "message": "No intent with that ID exists"
}

Common status codes:

Code	Meaning
`400`	Bad request — malformed body or invalid field
`401`	Missing or invalid API key
`404`	Resource not found
`409`	Conflict — intent already exists with that ID
`429`	Rate limited — back off and retry
`500`	Gateway error — check logs