Skip to main content
POST
/
relay
curl -X POST http://localhost:9090/relay \
  -H "Content-Type: application/json" \
  -d '{
    "origin_chain": "base",
    "tx_hash": "0xabc123..."
  }'

{
  "messages": [
    {
      "message_id": "a1b2c3d4e5f6...",
      "origin": 8453,
      "destination": 1,
      "nonce": 42
    }
  ]
}
Submit an on-chain transaction for fast relay. The relayer extracts any Hyperlane messages from the transaction, filters to eligible messages (currently CCTP V2 only), and immediately enqueues them for delivery — bypassing the normal block-polling delay.
Non-eligible messages (e.g. non-CCTP V2) are silently skipped. The response only contains messages that were accepted. An empty messages array means the transaction contained no eligible Hyperlane messages.
curl -X POST http://localhost:9090/relay \
  -H "Content-Type: application/json" \
  -d '{
    "origin_chain": "base",
    "tx_hash": "0xabc123..."
  }'

{
  "messages": [
    {
      "message_id": "a1b2c3d4e5f6...",
      "origin": 8453,
      "destination": 1,
      "nonce": 42
    }
  ]
}

​
Errors

StatusReasonDescription
400 Bad Requestinvalid_requestorigin_chain or tx_hash is empty, exceeds max length, or the chain is not found.
400 Bad Requestmessage_not_whitelistedA message in the transaction does not match the relayer’s whitelist.
400 Bad Requestmessage_blacklistedA message in the transaction matches the relayer’s blacklist.
400 Bad Requestunsupported_destinationThe message destination chain is not configured on this relayer.
400 Bad Requesttoo_many_messagesThe transaction contains more than 10 Hyperlane messages.
408 Request TimeouttimeoutThe transaction receipt was not found within 10 seconds. Retry after the transaction is confirmed.
429 Too Many Requestsrate_limitedThe global rate limit has been exceeded. Retry after a short backoff.
429 Too Many Requestsduplicate_txThe same (origin_chain, tx_hash) was already submitted within the last 5 minutes.
503 Service Unavailablecache_fullThe deduplication cache is full. Retry shortly.
500 Internal Server Error—An internal error occurred. The request can be retried safely unless messages were partially enqueued.

​
Eligibility

Currently only CCTP V2 messages on EVM chains are eligible. A transaction qualifies when the number of MessageSent events from Circle’s MessageTransmitter V2 contract equals the number of Hyperlane Dispatch events. Messages that do not meet this criterion are silently omitted from the response rather than causing an error.

​
Deduplication

The relayer maintains a 5-minute deduplication window per (origin_chain, tx_hash) pair. Submitting the same transaction a second time within this window returns 429 Too Many Requests. After 5 minutes the same hash can be resubmitted. If the request fails with a non-2xx status the reservation is released immediately so the client can retry right away.

​
Health Check

A GET /relay request returns 200 OK with body up and can be used as a liveness probe. 
curl http://localhost:9090/relay
# up