API
Solver Bus is an additional system component that optimizes frontends←→solvers quoting, and intent discovery process. Any frontend app may use a generic foundation-hosted Solver Bus or launch its own instance to customize preferred solver accounts.
Near Intents protocol may operate without a Solver Relay component:
frontends may use any other quoting mechanisms to compose an intent for the end user
solvers may index Near blockchain to find intents to fill.
However, using Solver Relay is recommended for speed optimization goals.
Frontend JSON-RPC Endpoint
POST: https://solver-relay-v2.chaindefuser.com/rpc
1. Quote asset prices from solvers
Allow the front end to estimate potential output for a given exact input or the required input for a given exact output based on user intent. The solver relay will forward a quote request to all connected solvers, wait for up to 3000 ms, and return all available quote options to the user. Only one of exact_amount_in
or exact_amount_out
should be provided in the request, not both.
Parameters
defuse_asset_identifier_in
- asset to trade fromdefuse_asset_identifier_out
- asset to trade toexact_amount_in
- amount of token_in for exchangeexact_amount_out
- amount of token_out for exchangemin_deadline_ms
(optional) - minimum validity time for an offer from solvers (in milliseconds). The shorter the time, the better the price solvers can offer. Default is 60000 (1 minute).
Response
array of quote responses from solvers
quote_hash
- quote response hashdefuse_asset_identifier_in
- asset to trade fromdefuse_asset_identifier_out
- asset to trade toamount_in
:If
exact_amount_in
is defined: Specifies token_in amount for the exchange.If
exact_amount_in
is not defined: Represents a proposed amount of token_in.
amount_out
:If
exact_amount_out
is defined: Specifies token_out amount for the exchange.If
exact_amount_out
is not defined: Represents a proposed amount of token_out.
expiration_time
- expiration date of the offer from the solver
Example
// Request
{
"id": 1,
"jsonrpc": "2.0",
"method": "quote",
"params": [
{
"defuse_asset_identifier_in": "nep141:ft1.near",
"defuse_asset_identifier_out": "nep141:ft2.near",
"exact_amount_in": "1000",
"min_deadline_ms": 60000 // OPTIONAL. default 60_000ms / 1min
}
]
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"quote_hash": "00000000000000000000000000000000",
"defuse_asset_identifier_in": "nep141:ft1.near",
"defuse_asset_identifier_out": "nep141:ft2.near",
"amount_in": "1000",
"amount_out": "2000"
"expiration_time": "2024-10-01T12:10:27Z"
},
// ...
]
}
2. Publish intent
If the user is satisfied with the offer provided by the solver, they can sign an intent and send it to the Solver Relay for execution along with the solver's quote hash(es). Relay supports these types of signatures for publishing intents: nep413
, erc191
, raw_ed25519
Parameters(NEP413)
quote_hashes
- quote response hashes from solverssigned_data
- data containing user intents with a signaturestandard
- content signature standard (nep413
)payload
- payload that was signedmessage
signer_id
- signer's account ID in Near Intentsintents[]
- array of user intentsintent
- intent typeother data depending on intent type
deadline
- deadline until which this intent is valid, ISO-8601 string
nonce
- unique nonce for operationrecipient
- Near Intents contract address (intents.near
)callbackUrl
(optional) - needed for some wallets
signature
- signature of the payloadpublic_key
- signer's public key
Parameters(ERC191)
quote_hashes
- quote response hashes from solversssigned_data
- data containing user intents with a signaturestandard
- content signature standard (erc191
)payload
- STRINGIFIED payload that was signedsigner_id
- signer's account ID in Near Intentsintents[]
- array of user intentsintent
- intent typeother data depending on intent type
deadline
- deadline until which this intent is valid, ISO-8601 stringnonce
- unique nonce for operationveryfying_contract
- Near Intents contract address (intents.near
)
signature
- signature of the payload
Parameters(RAW_ED25519)
quote_hashes
- quote response hashes from solverssigned_data
- data containing user intents with a signaturestandard
- content signature standard (raw_ed25519
)payload
- STRINGIFIED payload that was signedsigner_id
- signer's account ID in Near Intentsintents[]
- array of user intentsintent
- intent typeother data depending on intent type
deadline
- deadline until which this intent is valid, ISO-8601 stringnonce
- unique nonce for operationveryfying_contract
- Near Intents contract address (intents.near
)
signature
- signature of the payloadpublic_key
- signer's public key
TokenDiff Intent
intent
- intent type (equalstoken_diff
)diff
- map where:Keys: Represent
defuse_asset_identifiers
of tokens.Values: Represent amounts for the tokens as strings.
Positive values indicate tokens to be received by the account.
Negative values (prefixed with "-") indicate tokens to be transferred from the account.
Response
status
- intent receiving status (OK
orFAILED
)reason
- error reason (if the status isFAILED
)intent_hash
- intent identifier
Example
// Request
{
"id": 1,
"jsonrpc": "2.0",
"method": "publish_intent",
"params": [
{
"quote_hashes": ["00000000000000000000000000000000", ...],
"signed_data": {
"standard": "nep413",
"message": {
"signer_id": "user.near",
"deadline": "2024-10-14T12:53:40.000Z",
"intents": [
{
"intent": "token_diff",
"diff": {
"nep141:ft1.near": "300",
"nep141:ft2.near": "-500"
}
},
{
"intent": "mt_batch_transfer",
"receiver_id": "referral.near",
"token_id_amounts": {
"nep141:ft1.near": "1"
}
},
{
"intent": "ft_withdraw",
"token": "ft1.near",
"receiver_id": "ft1.near",
"amount": "299",
"memo": "WITHDRAW_TO:address_on_target_chain"
}
]
},
"nonce": "bacFZfjWD8lm4mwAZ/TScL8HrrapeXlTSyAeD4i8Lfs=",
"recipient": "intents.near",
"signature": "ed25519:2yJ1ANYAL1yRoXk8uiDZygyH3TeRpVucwBMpUh1bsvcCLL3BBoJzqAojQNN4mxz9v5fSzbwqz7p9MFtZKNKW81Cg",
"public_key": "ed25519:4vyWshm6BE4uoHk7fot2iij7tFXrjWp4wDnNEJx2W4sf"
}
}
]
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result":
{
"status": "FAILED",
"reason": "expired",
"intent_hash": "00000000000000000000000000000000"
}
}
3. Get intent status
Check the status of intent execution.
Response
intent_hash
- intent identifierstatus
- intent execution statusdata
- additional datahash
- Near transaction hash (if available)
Statuses
PENDING
- the intent was successfully received by the Relay and is pending the executionTX_BROADCASTED
- transaction for the intent has been successfully sent to the Near Intents contractSETTLED
- the intent has been successfully settled on chainNOT_FOUND_OR_NOT_VALID
- the intent wasn't received successfully, has expired, or there was an error when executing it on chain
Example
// Request
{
"id": 1,
"jsonrpc": "2.0",
"method": "get_status",
"params": [
{
"intent_hash": "00000000000000000000000000000000"
}
]
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"intent_hash": "00000000000000000000000000000000"
"status": "SETTLED",
"data": {
"hash": "8yFNEk7GmRcM3NMJihwCKXt8ZANLpL2koVFWWH1MEEj"
}
}
}
Solver WS Endpoint
wss://solver-relay-v2.chaindefuser.com/ws
1. Subscribe to quote/quote_status requests
Example
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "subscribe",
"params": ["quote"]
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "00000000-0000-0000-0000-000000000000", // subscriptionId
}
defuse_asset_identifier_out
- asset to trade to
2. Receive quote requests
Event data
subscription
- subscription identifierquote_id
- quote request identifierdefuse_asset_identifier_in
- asset to trade fromdefuse_asset_identifier_out
- asset to trade toexact_amount_in
- amount of token_in for exchangeexact_amount_out
- amount of token_out for exchangeCondition: Only one of
exact_amount_in
orexact_amount_out
can will be specified in a request.
min_deadline_ms
- minimum validity time for an offer from solvers (in milliseconds). The shorter the time, the better the price solvers can offer.
Example
// Event
{
"jsonrpc": "2.0"
"method": "subscribe",
"params": {
"subscription": "00000000-0000-0000-0000-000000000000",
"quote_id":"00000000-0000-0000-0000-000000000000",
"defuse_asset_identifier_in": "nep141:ft1.near",
"defuse_asset_identifier_out": "nep141:ft2.near",
"exact_amount_in": "1000",
"min_deadline_ms": 60000
}
}
3. Respond to quote requests
Parameters
quote_id
- quote request identifierquote_output
- quote resultamount_out
- proposedamount
forexact_amount_in
requestsamount_in
- proposedamount
forexact_amount_out
requests
signed_data
- data containing solver intents with a signaturestandard
- content signature standard (nep413
)payload
- payload that was signedmessage
signer_id
- solver's account ID in Near Intentsintents[]
- array of intentsintent
- intent typeother data depending on intent type
deadline
- deadline until which this intent is valid, ISO-8601 string
nonce
- unique nonce for operationrecipient
- Near Intents contract address (intents.near
)
signature
- signature of the payloadpublic_key
- signer's (solver's) public key
other_quote_hashes
- hashes of other quote results to fulfill the current intent (optional)
Example
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "quote_response",
"params": [
{
"quote_id":"00000000-0000-0000-0000-000000000000",
"quote_output": {
"amount_out": "300",
},
"signed_data": {
"standard": "nep413",
"message": {
"signer_id": "solver.near",
"deadline": "2024-10-14T12:53:40.000Z",
"intents": [
{
"intent": "token_diff",
"diff": {
"nep141:ft2.near": "-300",
"nep141:ft1.near": "500"
}
},
]
},
"nonce": "BJwLqfS+yJSMgjzWAXOULFgSfHWdlK4Uso65/jeVUrA=",
"recipient": "intents.near",
"signature": "ed25519:5193Sx4eC6f3YdztiUfg2MSWJBuqi9Ykbuh3NEzw9b3nQQCCkT84YmJZoN4dpjc8g4rx1D5o2asesR5ECtGa5vFQ",
"public_key": "ed25519:AgYQSY8hemfdL8ENQqwBrVoohB5d6j972qwgWgPgjgiZ"
}
},
"other_quote_hashes": ["00000000000000000000000000000000", ...] //optional
]
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "OK",
}
4.Receive quote_status event
Event data
quote_hash
- solver's intent hash used to identify the quote responseintent_hash
- user's intent hash (identifier)tx_hash
- hash of the mined intent transaction on Near
Example
// Event
{
"jsonrpc": "2.0"
"method": "subscribe",
"params": {
"quote_hash": "00000000000000000000000000000000",
"intent_hash":"00000000000000000000000000000000",
"tx_hash": "00000..."
}
}
5. Unsubscribe
Last updated