Protocol API

The Protocol API is the direction resolvers call on Utexo. Callbacks Utexo makes on the resolver are documented in the Resolver API. The interactive reference for these endpoints is the Resolver API Swagger.

Authentication

Every request must include your resolver API key:

X-API-Key: <your_api_key>

Requests with missing or invalid keys are rejected.

Error envelope

Protocol errors use this envelope:

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

Discovery

`GET /v1/networks`

Lists supported networks. Response items include:

Field	Description
`id`	Numeric network identifier.
`name`	Human-readable network name.
`type`	Network family.
`supports_optimized_swap`	Whether the network supports optimized single-chain swaps.
`icon_url`	Icon asset URL.
`supports_custom_tokens`	If `true`, the token list is not exhaustive and custom tokens may be swapped.

`GET /v1/tokens`

Lists supported tokens. Query parameters:

Parameter	Type	Description
`limit`	integer	Page size.
`offset`	integer	Page offset.
`q`	string	Symbol or contract address filter.
`network_id`	integer	Restrict to a network.

Response:

{
  "data": [
    {
      "network_id": "<integer>",
      "name": "<token name>",
      "contract_address": "<token address>",
      "symbol": "<symbol>",
      "icon_url": "<URL>",
      "wrapped_token_address": null
    }
  ],
  "pagination": {
    "limit": "<integer>",
    "offset": "<integer>",
    "pages": "<integer>",
    "total": "<integer>"
  }
}

`GET /v1/resolvers/webhooks/public-key`

Returns the Ed25519 public key used to verify webhook signatures.

{ "public_key": "<hex-encoded Ed25519 public key>" }

Intents and swaps

`GET /v1/intents/{id}`

Retrieves an intent. Statuses:

Status	Meaning
`Initiated`	Intent created; awaiting user approval.
`ApprovalAdded`	User approval received.
`Accepted`	Intent accepted by the resolver and being executed.
`Declined`	Intent declined; will not execute.

Notable fields (non-exhaustive): chain and token identifiers, source and destination addresses, resolver_id, deadline, nonce, amount lots and decimals, quote_id, slippage_tolerance_bps, intermediate-token bounds, affiliate_id, swap_type (standard or optimized), resolver_deposit_address, deposit_type (escrowed or direct), and lifecycle timestamps.

`GET /v1/intents/status/pending`

Lists intents that are waiting for a resolver decision. Query parameters: limit (default page size 20) and offset. The response is paginated.

`POST /v1/intents/{id}/accept`

Accepts an intent. The response carries the data the resolver needs for the deposit transaction: system_contract_address, permit2_contract_address, permit2_signature, proxy_address, fulfillment_signature, psbt, and cosign_transaction. Which fields are meaningful depends on the source chain. Errors: 403 (this resolver may not update the intent), 404, 409 (the intent is no longer in a state that can be accepted), 500.

`POST /v1/intents/{id}/decline`

Declines an intent. The body is optional:

{ "error_code": 1, "message": "quote expired" }

Errors: 403, 404, 409, 500.

`POST /v1/intents/{intent_id}/refund`

Refunds the user’s locked funds without waiting for the timelock to expire.

`GET /v1/resolvers/stream`

Opens a WebSocket stream for the resolver (HTTP 101 Switching Protocols). Send the X-API-Key header on the upgrade request.

`GET /v1/swaps/{intent_id}/swap`

Retrieves the on-chain execution record for an intent. Notable fields: status, proxy_address, deposit/fulfill/withdraw/swap transaction hashes, intermediate-token data, and lifecycle timestamps.

Reporting transactions

Resolvers must report each on-chain step. For standard swaps, report the Deposit, then the Fulfill.

`POST /v1/intents/{id}/deposit`

{ "tx_hash": "<transaction hash>" }

`POST /v1/intents/{id}/fulfill`

{
  "tx_hash": "<transaction hash>",
  "signature": "<signature>"
}

signature is optional for EVM, Solana, and Tron. It is required for Bitcoin.

Optimized swaps report only the Swap step. Confirm the reporting endpoint for optimized swaps with Utexo during onboarding.

Secret retrieval

`GET /v1/intents/{id}/reveal-secret`

{ "secret": "<32-byte secret>" }

`POST /v1/intents/batch/reveal-secrets`

Request:

{ "intent_ids": ["<uuid>"] }

Response:

{ "secrets": { "<uuid>": "<secret>" } }

Health

`GET /v1/system/live`

Requires the X-API-Key header, like every Protocol API request.

200 — healthy
400 — the X-API-Key header is missing or malformed (error code 14)
500 — unhealthy

No response body is documented.

What Utexo Is

Getting Started

Product Suite

API Reference

Authentication

Error envelope

Discovery

`GET /v1/networks`

`GET /v1/tokens`

`GET /v1/resolvers/webhooks/public-key`

Intents and swaps

`GET /v1/intents/{id}`

`GET /v1/intents/status/pending`

`POST /v1/intents/{id}/accept`

`POST /v1/intents/{id}/decline`

`POST /v1/intents/{intent_id}/refund`

`GET /v1/resolvers/stream`

`GET /v1/swaps/{intent_id}/swap`

Reporting transactions

`POST /v1/intents/{id}/deposit`

`POST /v1/intents/{id}/fulfill`

Secret retrieval

`GET /v1/intents/{id}/reveal-secret`

`POST /v1/intents/batch/reveal-secrets`

Health

`GET /v1/system/live`

​Authentication

​Error envelope

​Discovery

​GET /v1/networks

​GET /v1/tokens

​GET /v1/resolvers/webhooks/public-key

​Intents and swaps

​GET /v1/intents/{id}

​GET /v1/intents/status/pending

​POST /v1/intents/{id}/accept

​POST /v1/intents/{id}/decline

​POST /v1/intents/{intent_id}/refund

​GET /v1/resolvers/stream

​GET /v1/swaps/{intent_id}/swap

​Reporting transactions

​POST /v1/intents/{id}/deposit

​POST /v1/intents/{id}/fulfill

​Secret retrieval

​GET /v1/intents/{id}/reveal-secret

​POST /v1/intents/batch/reveal-secrets

​Health

​GET /v1/system/live

Authentication

Error envelope

Discovery

`GET /v1/networks`

`GET /v1/tokens`

`GET /v1/resolvers/webhooks/public-key`

Intents and swaps

`GET /v1/intents/{id}`

`GET /v1/intents/status/pending`

`POST /v1/intents/{id}/accept`

`POST /v1/intents/{id}/decline`

`POST /v1/intents/{intent_id}/refund`

`GET /v1/resolvers/stream`

`GET /v1/swaps/{intent_id}/swap`

Reporting transactions

`POST /v1/intents/{id}/deposit`

`POST /v1/intents/{id}/fulfill`

Secret retrieval

`GET /v1/intents/{id}/reveal-secret`

`POST /v1/intents/batch/reveal-secrets`

Health

`GET /v1/system/live`