> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get the zero-fee subsidy status
> Returns whether zero-fee orders on the subsidized route (Arbitrum USDC to Arbitrum USDG) can fill now, why not, and when that is expected to change. "available" does not guarantee capacity for a given order size.
## OpenAPI
````yaml /v1.0.0/api-reference/openapi.yml get /v1/transit/subsidy
openapi: 3.0.0
info:
title: Paxos Labs API
description: >
Paxos Labs API V2.
---
# API overview
This document describes shared behavior and conventions for the Paxos Labs
API (REST and GraphQL).
Health check
A **health** endpoint is available for orchestrators (GitHub Actions, etc).
| Item |
Details
|
| ------------ |
---------------------------------------------------------------------------------------
|
| **Path** | `GET /health` (no version prefix; no API key or rate limit
applied). |
| **Response** | `200` with Terminus-style JSON when healthy; `503` when
unhealthy (e.g. database down). |
**Docker / healthcheck:** If your healthcheck uses `curl` (e.g. `curl -f
http://localhost:3000/health`), ensure your image has curl installed. Base
images like `node:bullseye-slim` or `node:alpine` do not—install it (e.g.
`RUN apk add --no-cache curl` for Alpine).
GraphQL endpoint
A **GraphQL** API is available in addition to REST. Use it to query address
book and vault data with a single request and flexible field selection.
| Item |
Details |
| ---------------------------- |
-------------------------------------------------------------------- |
| **Altair (interactive IDE)** |
[https://api.paxoslabs.com/altair](https://api.paxoslabs.com/altair) |
| **GraphQL endpoint** | Same base URL with path `/graphql` for
POST. |
| **Authentication** | Same as REST: send `x-api-key`
header. |
Open the Altair link in a browser to explore the schema and run queries.
Filter query parameter syntax
List endpoints that support a `filter` query parameter use a single string
with **keys**, **operators**, and **combinators**. This keeps the number of
query params small (AIP-160 style) while allowing flexible filtering.
Operators
| Operator | Meaning | Example |
| -------- | ---------- | ------------------ |
| `=` | Equals | `chainId=1` |
| `!=` | Not equals | `status!=REFUNDED` |
Combinators
| Combinator | Meaning |
Example |
| ---------- | -------------------------------------------- |
------------------------------- |
| `AND` | All conditions must match (case-insensitive) | `chainId=1 AND
name="Treasury"` |
| `OR` | Any condition may match (case-insensitive) | `chainId=1 OR
chainId=137` |
Value formatting
| Type | Use case |
Example |
| -------- | ----------------------------------------- |
------------------------- |
| Unquoted | Numbers, booleans, single-token values | `chainId=1`,
`valid=true` |
| Quoted | Strings with spaces or special characters | `name="Treasury
Wallet"` |
| Escape | Literal quote inside a quoted string |
`\"` |
Allowed **keys** and **value types** (number, hex address, string, etc.) are
defined per endpoint in the API docs and validated by the server.
Possible combinations (examples)
| Category |
Example |
| --------------------- |
--------------------------------------------------- |
| Single condition |
`chainId=1` |
| Single condition |
`status!=REFUNDED` |
| AND | `chainId=1 AND
name="Treasury"` |
| AND | `vaultAddress=0x123... AND
chainId=1` |
| OR | `chainId=1 OR
chainId=137` |
| OR | `status=PENDING OR
status=COMPLETE` |
| Mixed AND and OR | `chainId=1 AND (status=PENDING OR
status=COMPLETE)` |
| Equals and not-equals | `chainId=1 AND
status!=REFUNDED` |
| Equals and not-equals |
`name!=""` |
Mixed AND and OR: AND has higher precedence; use parentheses for grouping.
Without grouping, evaluation is left-to-right per implementation.
Implementation note
| Item |
Details |
| --------- |
------------------------------------------------------------------------- |
| Location |
`src/common/utils/filter.util.ts` |
| Supported | `=`, `!=`, `AND`,
`OR` |
| Errors | Invalid keys or value types return `400` with the standard
error envelope |
version: '2.0'
contact: {}
servers:
- url: https://api.paxoslabs.com/
description: Production
security: []
tags: []
paths:
/v1/transit/subsidy:
get:
tags:
- Transit
- Transit
summary: Get the zero-fee subsidy status
description: >-
Returns whether zero-fee orders on the subsidized route (Arbitrum USDC
to Arbitrum USDG) can fill now, why not, and when that is expected to
change. "available" does not guarantee capacity for a given order size.
operationId: getTransitSubsidy
parameters:
- name: distributorCode
required: false
in: query
description: >-
Optional 32-byte hex code (0x + 64 hex chars) to check the subsidy
for. When omitted, uses the organization's default distributor code
if one is configured, otherwise the zero hash — the same code an
order quote would use. Only your organization's distributor code or
the zero hash may be set: any other code is refused with 403, and
setting a non-zero code without an API key is refused with 401.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetTransitSubsidyResponseDto'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: A non-zero distributorCode was set without an API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'403':
description: distributorCode is not your organization's distributor code
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'503':
description: The subsidy status could not be read; retry
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
security:
- {}
- api-key: []
components:
schemas:
GetTransitSubsidyResponseDto:
type: object
properties:
sourceChainId:
type: number
description: EVM chain ID of the source chain of the subsidized route.
example: 42161
destinationChainId:
type: number
description: EVM chain ID of the destination chain of the subsidized route.
example: 42161
offerAsset:
type: string
description: Offer asset address on the source chain.
example: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
wantAsset:
type: string
description: Want asset address on the destination chain.
example: '0x004b506865409877c9fa29bfb1eba929984b9bbc'
state:
type: string
description: >-
"available": zero-fee orders can fill now. This does not guarantee
capacity for a given order size. "unavailable": zero-fee orders
cannot fill; `reason` says why. "unknown": the status could not be
determined right now; treat the subsidy as not guaranteed.
enum:
- available
- unavailable
- unknown
example: unavailable
reason:
type: string
description: >-
Present when `state` is "unavailable". "scheduled-closure": closed
outside the subsidy schedule (weekends and US market holidays).
"not-eligible": the distributor code is not enabled for the subsidy.
"temporarily-unavailable": paused. "capacity-exhausted": today's
zero-fee limit for this distributor code is used up, including
orders that are already waiting to fill.
enum:
- scheduled-closure
- capacity-exhausted
- not-eligible
- temporarily-unavailable
example: scheduled-closure
closesAt:
type: string
description: >-
Present when `state` is "available". When the subsidy next closes on
its schedule (RFC 3339 UTC); null when no closure is scheduled
within the next 14 days.
nullable: true
example: '2026-10-23T19:00:00Z'
allowance:
description: >-
Present when `state` is "available". The daily zero-fee allowance of
the distributor code checked; null when no daily limit applies to
it.
nullable: true
type: object
allOf:
- $ref: '#/components/schemas/TransitSubsidyAllowanceDto'
expectedReopenAt:
type: string
description: >-
Present when `state` is "unavailable". When zero-fee orders are
expected to fill again (RFC 3339 UTC); null when no reopening is
scheduled. For "capacity-exhausted" this is when the next day's
limit starts; if the orders already waiting are larger than a full
day's limit, check again then.
nullable: true
example: '2026-10-26T04:00:00Z'
observedAt:
type: string
description: When this status was observed (RFC 3339 UTC).
example: '2026-10-24T16:00:00Z'
required:
- sourceChainId
- destinationChainId
- offerAsset
- wantAsset
- state
- observedAt
ErrorResponseDto:
type: object
properties:
error:
description: Error object containing details
allOf:
- $ref: '#/components/schemas/ErrorObjectDto'
required:
- error
TransitSubsidyAllowanceDto:
type: object
properties:
remainingAmount:
type: string
description: >-
How much a new zero-fee order from this distributor code can still
fill today, as a decimal string in USDG base units (6 decimals, so
1000000 is 1 USDG). Orders from this code that are already waiting
to fill come first, so their amounts are already subtracted. An
order submitted in the last few minutes may not be subtracted yet,
so a new order can get less.
example: '500000000'
dailyCapAmount:
type: string
description: >-
This distributor code's daily zero-fee limit, as a decimal string in
USDG base units.
example: '1000000000'
resetsAt:
type: string
description: >-
When the daily allowance renews to `dailyCapAmount` (RFC 3339 UTC).
The subsidy can still be closed on its schedule at that time; see
`closesAt`.
example: '2026-10-22T04:00:00Z'
required:
- remainingAmount
- dailyCapAmount
- resetsAt
ErrorObjectDto:
type: object
properties:
code:
type: number
description: HTTP status code
example: 400
message:
type: string
description: Human-readable error message
example: Invalid filter syntax.
status:
type: string
description: Error status enum value
enum:
- UNKNOWN
- INVALID_ARGUMENT
- NOT_FOUND
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- INTERNAL
- METHOD_NOT_ALLOWED
example: INVALID_ARGUMENT
details:
description: Additional error details
type: array
items:
$ref: '#/components/schemas/ErrorDetailDto'
required:
- code
- message
- status
ErrorDetailDto:
type: object
properties:
'@type':
type: string
description: Type URL identifying the error detail schema
example: type.paxoslabs.dev/errors/BadRequest
fieldViolations:
description: Field-level violations for validation errors
type: array
items:
$ref: '#/components/schemas/FieldViolationDto'
required:
- '@type'
FieldViolationDto:
type: object
properties:
field:
type: string
description: The field that caused the violation
example: filter
description:
type: string
description: Description of the violation
example: vaultAddress 0x0x is an invalid hex address.
required:
- field
- description
securitySchemes:
api-key:
type: apiKey
in: header
name: x-api-key
description: 'API key in format: pxl__'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.