Backend API
The BackendApiService provides a comprehensive HTTP client for the SODAX backend API, covering intent lookup, swap submission, solver orderbook, money market data, and runtime configuration. It implements IConfigApi so that ConfigService and other services can fetch dynamic chain/token configuration without coupling to a concrete HTTP implementation.
The service is automatically instantiated when you create a Sodax instance and is available as sodax.backendApi.
All public methods return Promise<Result<T>> — they never throw. On network failure, timeout, or a non-2xx HTTP response the returned Result has ok: false with a descriptive Error in the error field.
Table of Contents
Initialization
BackendApiService is automatically created when you construct a Sodax instance. Access it via sodax.backendApi.
Basic Initialization
Custom Configuration
Initialization with sodax.config
sodax.configIf you need dynamic chain/token config fetched from the backend, call initialize() on ConfigService after construction. BackendApiService is the underlying HTTP transport that ConfigService uses.
Configuration
ApiConfig Type
ApiConfig TypeRequestOverrideConfig Type
RequestOverrideConfig TypeEvery public method accepts an optional RequestOverrideConfig as its last argument. These per-call overrides take precedence over the ApiConfig the service was constructed with.
Default Configuration
Result<T> and Error Handling
All public methods return Promise<Result<T>>, defined as:
Never use try/catch around backendApi calls — errors are always captured in the Result.
Checking results
Error codes on error.message
error.messageerror.message
Meaning
'HTTP_REQUEST_FAILED'
Non-2xx HTTP response. Check error.cause for HTTP <status>: <body>.
'REQUEST_TIMEOUT'
Request exceeded the configured timeout. Check error.cause for the timeout duration.
'UNKNOWN_REQUEST_ERROR'
Any other unexpected failure.
Intent Endpoints
Get Intent by Transaction Hash
Retrieves swap intent details using a hub-chain transaction hash.
Signature:
Method: GET
Endpoint:
/intent/tx/{txHash}
Response type:
Get Intent by Intent Hash
Retrieves swap intent details using a canonical intent hash.
Signature:
Method: GET
Endpoint:
/intent/{intentHash}
Response: Same as IntentResponse above.
Get User Intents
Retrieves a paginated list of all swap intents created by a specific wallet address, with optional date-range filtering.
startDate and endDate are Unix timestamps in milliseconds.
Signature:
Method: GET
Endpoint:
/intent/user/{userAddress}?startDate=…&endDate=…&limit=…&offset=…
Response type:
Swap Endpoints
Submit Swap Transaction
Submits a signed spoke-chain swap transaction to the backend for relay processing. The backend relays the transaction to the hub chain, posts execution data to the solver, and advances the intent through its lifecycle.
Signature:
Method: POST
Endpoint:
/swaps/submit-tx
Get Submit Swap Transaction Status
Polls the backend relay pipeline for the current status of a previously submitted swap transaction.
Status progresses through: pending → verifying → verified → relaying → relayed → posting_execution → executed (or failed).
Signature:
Method: GET
Endpoint:
/swaps/submit-tx/status?txHash=…&srcChainKey=…
Solver Endpoints
Get Orderbook
Retrieves a paginated snapshot of the solver orderbook — open swap intents waiting to be filled.
Signature:
Method: GET
Endpoint:
/solver/orderbook?offset={offset}&limit={limit}
Response type:
Money Market Endpoints
Get User Position
Retrieves the current money market position for a wallet address — all reserves where the user holds aTokens (supplied collateral) or variable-debt tokens (outstanding borrows).
Signature:
Method: GET
Endpoint:
/moneymarket/position/{userAddress}
Response type:
Get All Money Market Assets
Retrieves on-chain state snapshots for every active money market reserve asset.
Signature:
Method: GET
Endpoint:
/moneymarket/asset/all
Response type:
Get Specific Money Market Asset
Retrieves the on-chain state snapshot for a single money market reserve asset.
Signature:
Method: GET
Endpoint:
/moneymarket/asset/{reserveAddress}
Response: MoneyMarketAsset (same interface as above).
Get Asset Borrowers
Retrieves a paginated list of wallets with an outstanding borrow against a specific reserve.
Signature:
Method: GET
Endpoint:
/moneymarket/asset/{reserveAddress}/borrowers?offset={offset}&limit={limit}
Response type:
Get Asset Suppliers
Retrieves a paginated list of wallets with an active supply (aToken balance) in a specific reserve.
Signature:
Method: GET
Endpoint:
/moneymarket/asset/{reserveAddress}/suppliers?offset={offset}&limit={limit}
Response type:
Get All Money Market Borrowers
Retrieves a paginated list of all wallet addresses that hold an active borrow position across any reserve.
Signature:
Method: GET
Endpoint:
/moneymarket/borrowers?offset={offset}&limit={limit}
Response type:
Config Endpoints
These methods implement IConfigApi and are consumed internally by ConfigService. You generally do not call them directly — use sodax.config instead. They are documented here for completeness and for custom IConfigApi implementations.
getAllConfig()
GET /config/all
GetAllConfigApiResponse — full SodaxConfig bundle
getChains()
GET /config/spoke/chains
GetChainsApiResponse — array of supported SpokeChainKey strings
getSwapTokens()
GET /config/swap/tokens
GetSwapTokensApiResponse — Record<SpokeChainKey, readonly XToken[]>
getSwapTokensByChainId(chainKey)
GET /config/swap/{chainKey}/tokens
GetSwapTokensByChainIdApiResponse
getMoneyMarketTokens()
GET /config/money-market/tokens
GetMoneyMarketTokensApiResponse
getMoneyMarketTokensByChainId(chainKey)
GET /config/money-market/{chainKey}/tokens
GetMoneyMarketTokensByChainIdApiResponse
getMoneyMarketReserveAssets()
GET /config/money-market/reserve-assets
GetMoneyMarketReserveAssetsApiResponse — array of reserve Address strings
getRelayChainIdMap()
GET /config/relay/chain-id-map
GetRelayChainIdMapApiResponse — SpokeChainKey → relay chain ID map
getSpokeChainConfig()
GET /config/spoke/all-chains-configs
GetSpokeChainConfigApiResponse — full SpokeChainConfigMap
All methods accept an optional RequestOverrideConfig as their last argument and return Promise<Result<T>>.
Utility Methods
Set Custom Headers
Merges additional headers into the service's default header set. Useful for injecting authentication tokens or tracing headers at runtime without constructing a new service instance.
Get Base URL
Returns the base URL the service is currently pointing at.
Complete Example
Notes
All string amounts in responses are in wei format (18 decimals) unless the specific field description says otherwise.
Pagination parameters (
offsetandlimit) are strings, not numbers.All endpoints return JSON responses.
Error messages follow the CODE form (
SCREAMING_SNAKE_CASE) for transport failures (HTTP_REQUEST_FAILED,REQUEST_TIMEOUT). Checkerror.causefor the underlying detail.XToken.chainKeyis the field used on token objects to identify the chain (notxChainId).Chain constants are accessed via
ChainKeys.*(e.g.ChainKeys.ETHEREUM_MAINNET), not legacy*_CHAIN_IDconstants.
Last updated