Development

User Flow

The process involves two main participants: the user, who initiates the swap, and the resolver, who executes it.

The swap process starts with a quote request.

Quote Request

The user specifies the currency pair they would like to swap and the amount. The client sends these parameters to the Changelly DeFi Quote API. The API returns a quote, a time-limited execution estimate that includes all pricing information.

Intent Creation

After receiving a quote, the client creates an intent, a structured representation of the user's swap intention, by specifying the user's addresses and the quote identifier the user agreed to. This represents the user's intention to execute the swap under the quoted conditions.

Signing an Intent

After intent creation, the API provides all the necessary information for the user to sign the swap. The user signs the intent off-chain, cryptographically approving the swap parameters defined in the intent and authorizing resolvers to execute it according to the quoted conditions.

Execution

Once the user has signed an intent, the system notifies the winning resolver to start swap execution by depositing the maker's assets into an escrow contract on the source chain and then transferring the corresponding assets to the user. During execution, the user can query the Changelly DeFi Intent API to retrieve the swap status.

Authorization

Affiliates must include their assigned X-Api-Key value in the request header when making calls to the API. All requests are authenticated by validating this header, and any request sent without a valid X-Api-Key will be rejected. Make sure the header is added to every request to ensure proper authorization and access to protected endpoints.

Authentication Method

Send your API key in the X-Api-Key HTTP header:

X-Api-Key: <your_api_key>

Errors

The API returns errors in a consistent JSON format. Each error includes a numeric code, a short message, and the related entity.

Error Response Format:

application/json

{
  "code": 1,
  "message": "Internal server error",
  "entity": "Intent"
}

Error Codes:

Code	Message	Description / Notes
2	Unexpected swap status	Swap is in an invalid state for the requested operation
3	Serde error	Failed to serialize or deserialize data
4	Messaging error	Issue with internal messaging or event system
6	Base58 error	Base58 encoding/decoding failed
7	Not found	Requested resource does not exist
8	Hex error	Hex encoding/decoding failed
10	Approval error	Error during approval process
11	Permit2 error	Failed to generate or validate Permit2 signature
12	Intent status error	Invalid or unavailable intent status
13	Missing context	Required request context missing
14	Malformed header	Invalid HTTP headers
15	Serde server error	Server failed to serialize/deserialize
16	Token error	Invalid token or token mismatch
17	Resolver address error	Resolver address invalid or missing
19	Fulfillment request hash creation error	Failed to create fulfillment request hash
20	Fulfillment request hash signing error	Failed to sign fulfillment request hash
22	Incorrect swap type	Swap type does not match expected
23	Optimized swap unsupported	Attempted optimized swap not supported
24	Provider error	External provider failed
25	Balance error	Insufficient balance
26	Address validation failed	User or contract address invalid
27	Slippage validation failed	Provided slippage value invalid
28	Signature validation failed	User or system signature invalid
31	Resolver public key error	Resolver public key invalid or missing
32	Required public key missing	Public key required but not provided
33	BTC transaction builder error	Failed to build BTC transaction
35	Forbidden network pair	Swap between this source/dest network not allowed