> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trails.build/llms.txt
> Use this file to discover all available pages before exploring further.
# BuildOIFRefundTransaction
## Overview
The `BuildOIFRefundTransaction` endpoint returns the direct on-chain transaction needed to refund an expired or unfilled OIF (Open Intents Framework) order through its input settler. After the order's `orderExpiresAt` deadline passes without a solver fill, any wallet can broadcast this transaction to return funds to the user.
## Use Cases
* Refund an OIF order whose solver did not fill before expiry
* Self-serve recovery from a stranded OIF deposit
## Request Parameters
### Required Fields
* **intentId** (string): The intent whose OIF order should be refunded.
## Response
* **intentId** (string)
* **orderId** (string, optional): The on-chain OIF order ID, when known.
* **to** (string): Transaction `to` address — the input settler contract.
* **data** (string): Transaction calldata.
* **value** (string): Transaction value (bigint).
* **chainId** (number): Chain to broadcast on.
* **orderExpiresAt** (string, optional): The expiry timestamp; the refund cannot be submitted until after this time.
* **ready** (boolean): `true` when the order is in a state where the refund can be submitted now.
* **status** (string): Current order state.
## Example
```typescript theme={null}
const response = await fetch('https://trails-api.sequence.app/rpc/Trails/BuildOIFRefundTransaction', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Access-Key': 'YOUR_ACCESS_KEY'
},
body: JSON.stringify({ intentId: 'intent_abc123' })
});
const tx = await response.json();
if (!tx.ready) {
console.log('OIF order is not yet refundable. Status:', tx.status, 'expires:', tx.orderExpiresAt);
return;
}
const hash = await walletClient.sendTransaction({
to: tx.to,
data: tx.data,
value: BigInt(tx.value),
chainId: tx.chainId
});
```
OIF refunds are only available for intents that used the `OIF` route provider. See [Route Providers — OIF](/sdk/quote-providers#oif-open-intents-framework) for routing details.
## Next Steps
Inspect the intent's state and OIF order details
Notify Trails after broadcasting the refund
## OpenAPI
````yaml trails-api.gen.json post /rpc/Trails/BuildOIFRefundTransaction
openapi: 3.0.0
info:
title: Trails API
version: 0.0.1
servers:
- url: https://trails-api.sequence.app
description: Trails API
security: []
paths:
/rpc/Trails/BuildOIFRefundTransaction:
post:
tags:
- Trails
operationId: Trails-BuildOIFRefundTransaction
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BuildOIFRefundTransactionRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BuildOIFRefundTransactionResponse'
4XX:
description: Client error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorWebrpcEndpoint'
- $ref: '#/components/schemas/ErrorWebrpcRequestFailed'
- $ref: '#/components/schemas/ErrorWebrpcBadRoute'
- $ref: '#/components/schemas/ErrorWebrpcBadMethod'
- $ref: '#/components/schemas/ErrorWebrpcBadRequest'
- $ref: '#/components/schemas/ErrorWebrpcClientAborted'
- $ref: '#/components/schemas/ErrorWebrpcStreamLost'
- $ref: '#/components/schemas/ErrorUnauthorized'
- $ref: '#/components/schemas/ErrorPermissionDenied'
- $ref: '#/components/schemas/ErrorSessionExpired'
- $ref: '#/components/schemas/ErrorMethodNotFound'
- $ref: '#/components/schemas/ErrorRequestConflict'
- $ref: '#/components/schemas/ErrorAborted'
- $ref: '#/components/schemas/ErrorGeoblocked'
- $ref: '#/components/schemas/ErrorRateLimited'
- $ref: '#/components/schemas/ErrorProjectNotFound'
- $ref: '#/components/schemas/ErrorAccessKeyNotFound'
- $ref: '#/components/schemas/ErrorAccessKeyMismatch'
- $ref: '#/components/schemas/ErrorInvalidOrigin'
- $ref: '#/components/schemas/ErrorInvalidService'
- $ref: '#/components/schemas/ErrorUnauthorizedUser'
- $ref: '#/components/schemas/ErrorQuotaExceeded'
- $ref: '#/components/schemas/ErrorQuotaRateLimit'
- $ref: '#/components/schemas/ErrorNoDefaultKey'
- $ref: '#/components/schemas/ErrorMaxAccessKeys'
- $ref: '#/components/schemas/ErrorAtLeastOneKey'
- $ref: '#/components/schemas/ErrorTimeout'
- $ref: '#/components/schemas/ErrorInvalidArgument'
- $ref: '#/components/schemas/ErrorUnavailable'
- $ref: '#/components/schemas/ErrorQueryFailed'
- $ref: '#/components/schemas/ErrorIntentStatus'
- $ref: '#/components/schemas/ErrorIntentProtocolDeprecated'
- $ref: '#/components/schemas/ErrorNotFound'
- $ref: '#/components/schemas/ErrorUnsupportedNetwork'
- $ref: '#/components/schemas/ErrorClientOutdated'
- $ref: '#/components/schemas/ErrorIntentsSkipped'
- $ref: '#/components/schemas/ErrorQuoteExpired'
- $ref: '#/components/schemas/ErrorHighPriceImpact'
- $ref: '#/components/schemas/ErrorIntentsDisabled'
5XX:
description: Server error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorWebrpcBadResponse'
- $ref: '#/components/schemas/ErrorWebrpcServerPanic'
- $ref: '#/components/schemas/ErrorWebrpcInternalError'
- $ref: '#/components/schemas/ErrorUnexpected'
- $ref: '#/components/schemas/ErrorChainNodeHealth'
components:
schemas:
BuildOIFRefundTransactionRequest:
type: object
required:
- intentId
properties:
intentId:
type: string
BuildOIFRefundTransactionResponse:
type: object
required:
- intentId
- to
- data
- value
- chainId
- ready
- status
properties:
intentId:
type: string
orderId:
type: string
to:
type: string
data:
type: string
value:
type: string
chainId:
type: number
orderExpiresAt:
type: string
ready:
type: boolean
status:
type: string
ErrorWebrpcEndpoint:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcEndpoint
code:
type: number
example: 0
msg:
type: string
example: endpoint error
cause:
type: string
status:
type: number
example: 400
ErrorWebrpcRequestFailed:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcRequestFailed
code:
type: number
example: -1
msg:
type: string
example: request failed
cause:
type: string
status:
type: number
example: 400
ErrorWebrpcBadRoute:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcBadRoute
code:
type: number
example: -2
msg:
type: string
example: bad route
cause:
type: string
status:
type: number
example: 404
ErrorWebrpcBadMethod:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcBadMethod
code:
type: number
example: -3
msg:
type: string
example: bad method
cause:
type: string
status:
type: number
example: 405
ErrorWebrpcBadRequest:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcBadRequest
code:
type: number
example: -4
msg:
type: string
example: bad request
cause:
type: string
status:
type: number
example: 400
ErrorWebrpcClientAborted:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcClientAborted
code:
type: number
example: -8
msg:
type: string
example: request aborted by client
cause:
type: string
status:
type: number
example: 400
ErrorWebrpcStreamLost:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcStreamLost
code:
type: number
example: -9
msg:
type: string
example: stream lost
cause:
type: string
status:
type: number
example: 400
ErrorUnauthorized:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: Unauthorized
code:
type: number
example: 1000
msg:
type: string
example: Unauthorized access
cause:
type: string
status:
type: number
example: 401
ErrorPermissionDenied:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: PermissionDenied
code:
type: number
example: 1001
msg:
type: string
example: Permission denied
cause:
type: string
status:
type: number
example: 403
ErrorSessionExpired:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: SessionExpired
code:
type: number
example: 1002
msg:
type: string
example: Session expired
cause:
type: string
status:
type: number
example: 403
ErrorMethodNotFound:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: MethodNotFound
code:
type: number
example: 1003
msg:
type: string
example: Method not found
cause:
type: string
status:
type: number
example: 404
ErrorRequestConflict:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: RequestConflict
code:
type: number
example: 1004
msg:
type: string
example: Conflict with target resource
cause:
type: string
status:
type: number
example: 409
ErrorAborted:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: Aborted
code:
type: number
example: 1005
msg:
type: string
example: Request aborted
cause:
type: string
status:
type: number
example: 400
ErrorGeoblocked:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: Geoblocked
code:
type: number
example: 1006
msg:
type: string
example: Geoblocked region
cause:
type: string
status:
type: number
example: 451
ErrorRateLimited:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: RateLimited
code:
type: number
example: 1007
msg:
type: string
example: Rate-limited. Please slow down.
cause:
type: string
status:
type: number
example: 429
ErrorProjectNotFound:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: ProjectNotFound
code:
type: number
example: 1008
msg:
type: string
example: Project not found
cause:
type: string
status:
type: number
example: 401
ErrorAccessKeyNotFound:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: AccessKeyNotFound
code:
type: number
example: 1101
msg:
type: string
example: Access key not found
cause:
type: string
status:
type: number
example: 401
ErrorAccessKeyMismatch:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: AccessKeyMismatch
code:
type: number
example: 1102
msg:
type: string
example: Access key mismatch
cause:
type: string
status:
type: number
example: 409
ErrorInvalidOrigin:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: InvalidOrigin
code:
type: number
example: 1103
msg:
type: string
example: Invalid origin for Access Key
cause:
type: string
status:
type: number
example: 403
ErrorInvalidService:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: InvalidService
code:
type: number
example: 1104
msg:
type: string
example: Service not enabled for Access key
cause:
type: string
status:
type: number
example: 403
ErrorUnauthorizedUser:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: UnauthorizedUser
code:
type: number
example: 1105
msg:
type: string
example: Unauthorized user
cause:
type: string
status:
type: number
example: 403
ErrorQuotaExceeded:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: QuotaExceeded
code:
type: number
example: 1200
msg:
type: string
example: Quota request exceeded
cause:
type: string
status:
type: number
example: 429
ErrorQuotaRateLimit:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: QuotaRateLimit
code:
type: number
example: 1201
msg:
type: string
example: Quota rate limit exceeded
cause:
type: string
status:
type: number
example: 429
ErrorNoDefaultKey:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: NoDefaultKey
code:
type: number
example: 1300
msg:
type: string
example: No default access key found
cause:
type: string
status:
type: number
example: 403
ErrorMaxAccessKeys:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: MaxAccessKeys
code:
type: number
example: 1301
msg:
type: string
example: Access keys limit reached
cause:
type: string
status:
type: number
example: 403
ErrorAtLeastOneKey:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: AtLeastOneKey
code:
type: number
example: 1302
msg:
type: string
example: You need at least one Access Key
cause:
type: string
status:
type: number
example: 403
ErrorTimeout:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: Timeout
code:
type: number
example: 1900
msg:
type: string
example: Request timed out
cause:
type: string
status:
type: number
example: 408
ErrorInvalidArgument:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: InvalidArgument
code:
type: number
example: 2000
msg:
type: string
example: Invalid argument
cause:
type: string
status:
type: number
example: 400
ErrorUnavailable:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: Unavailable
code:
type: number
example: 2002
msg:
type: string
example: Unavailable resource
cause:
type: string
status:
type: number
example: 400
ErrorQueryFailed:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: QueryFailed
code:
type: number
example: 2003
msg:
type: string
example: Query failed
cause:
type: string
status:
type: number
example: 400
ErrorIntentStatus:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: IntentStatus
code:
type: number
example: 2004
msg:
type: string
example: Invalid intent status
cause:
type: string
status:
type: number
example: 422
ErrorIntentProtocolDeprecated:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: IntentProtocolDeprecated
code:
type: number
example: 3000
msg:
type: string
example: >-
Requested intent protocol version is outdated/deprecated. Please
upgrade your Trails SDK, see https://docs.sequence.build for more
information.
cause:
type: string
status:
type: number
example: 422
ErrorNotFound:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: NotFound
code:
type: number
example: 8000
msg:
type: string
example: Resource not found
cause:
type: string
status:
type: number
example: 400
ErrorUnsupportedNetwork:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: UnsupportedNetwork
code:
type: number
example: 8008
msg:
type: string
example: Unsupported network
cause:
type: string
status:
type: number
example: 422
ErrorClientOutdated:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: ClientOutdated
code:
type: number
example: 8009
msg:
type: string
example: Client is outdated
cause:
type: string
status:
type: number
example: 422
ErrorIntentsSkipped:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: IntentsSkipped
code:
type: number
example: 7000
msg:
type: string
example: >-
Intents skipped as client is attempting a transaction that does not
require intents
cause:
type: string
status:
type: number
example: 400
ErrorQuoteExpired:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: QuoteExpired
code:
type: number
example: 7001
msg:
type: string
example: Intent quote has expired. Please try again.
cause:
type: string
status:
type: number
example: 400
ErrorHighPriceImpact:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: HighPriceImpact
code:
type: number
example: 7002
msg:
type: string
example: Quote unavailable due to high price impact
cause:
type: string
status:
type: number
example: 422
ErrorIntentsDisabled:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: IntentsDisabled
code:
type: number
example: 9000
msg:
type: string
example: Intents service is currently unavailable
cause:
type: string
status:
type: number
example: 400
ErrorWebrpcBadResponse:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcBadResponse
code:
type: number
example: -5
msg:
type: string
example: bad response
cause:
type: string
status:
type: number
example: 500
ErrorWebrpcServerPanic:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcServerPanic
code:
type: number
example: -6
msg:
type: string
example: server panic
cause:
type: string
status:
type: number
example: 500
ErrorWebrpcInternalError:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: WebrpcInternalError
code:
type: number
example: -7
msg:
type: string
example: internal error
cause:
type: string
status:
type: number
example: 500
ErrorUnexpected:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: Unexpected
code:
type: number
example: 2001
msg:
type: string
example: Unexpected server error
cause:
type: string
status:
type: number
example: 500
ErrorChainNodeHealth:
type: object
required:
- error
- code
- msg
- status
properties:
error:
type: string
example: ChainNodeHealth
code:
type: number
example: 9001
msg:
type: string
example: Intent quote is unavailable due to interrupted chain node access
cause:
type: string
status:
type: number
example: 503
````