Gasless Relayer

Submit gasless on-chain transactions using EIP-2612 permit signatures. The relayer pays gas on your behalf.

CTF Approval

Approve the settlement contract to transfer your CTF (Conditional Token) positions gaslessly.

POST /api/v1/relayer/ctf-approval

Request Body

{
  "chainId": 137,
  "owner": "0xYourAddress...",
  "operator": "0xSettlementContract...",
  "approved": true,
  "deadline": "1735689600",
  "v": 27,
  "r": "0x...",
  "s": "0x..."
}

Field	Type	Description
chainId	int64	Chain ID (e.g., 137)
owner	address	Your wallet address
operator	address	Settlement contract to approve
approved	bool	true to approve, false to revoke
deadline	string	Permit expiration (Unix timestamp as string)
v	uint8	Signature component
r	string	Signature component (32 bytes hex)
s	string	Signature component (32 bytes hex)

Response

{
  "success": true,
  "tx_hash": "0xTransactionHash..."
}

Example

curl -X POST https://api.turbinefi.com/api/v1/relayer/ctf-approval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chainId": 137,
    "owner": "0xYourAddress",
    "operator": "0xSettlementContract",
    "approved": true,
    "deadline": "1735689600",
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }'

USDC Permit

Approve USDC spending gaslessly using an EIP-2612 permit. Use this for a one-time max approval so future orders don't need per-order permits.

POST /api/v1/relayer/usdc-permit

Request Body

{
  "chainId": 137,
  "owner": "0xYourAddress...",
  "spender": "0xSettlementContract...",
  "value": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
  "deadline": "1735689600",
  "v": 27,
  "r": "0x...",
  "s": "0x..."
}

Field	Type	Description
chainId	int64	Chain ID (e.g., 137)
owner	address	Your wallet address
spender	address	Contract to approve for spending
value	string	Amount to approve (as string). Use uint256.max for unlimited
deadline	string	Permit expiration (Unix timestamp as string)
v	uint8	Signature component
r	string	Signature component (32 bytes hex)
s	string	Signature component (32 bytes hex)

Response

{
  "success": true,
  "tx_hash": "0xTransactionHash..."
}

Example

curl -X POST https://api.turbinefi.com/api/v1/relayer/usdc-permit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chainId": 137,
    "owner": "0xYourAddress",
    "spender": "0xSettlementContract",
    "value": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
    "deadline": "1735689600",
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }'

CTF Redemption

Redeem CTF outcome tokens for USDC after a market resolves. The relayer submits the redeemPositionsWithPermit transaction on your behalf.

POST /api/v1/relayer/ctf-redemption

Request Body

{
  "chainId": 137,
  "owner": "0xYourAddress...",
  "collateralToken": "0xUSDCAddress...",
  "parentCollectionId": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "conditionId": "0xConditionId...",
  "indexSets": ["1", "2"],
  "deadline": "1735689600",
  "v": 27,
  "r": "0x...",
  "s": "0x...",
  "marketAddress": "0xMarketContract..."
}

Field	Type	Description
chainId	int64	Chain ID (e.g., 137)
owner	address	Your wallet address
collateralToken	address	USDC contract address
parentCollectionId	bytes32	Parent collection (use zero bytes for top-level)
conditionId	bytes32	Gnosis CTF condition identifier
indexSets	string[]	Outcome index sets to redeem (e.g., ["1", "2"])
deadline	string	Permit expiration (Unix timestamp as string)
v	uint8	Signature component
r	string	Signature component (32 bytes hex)
s	string	Signature component (32 bytes hex)
marketAddress	address	Market contract address (optional, for PNL tracking)

Response

{
  "success": true,
  "tx_hash": "0xTransactionHash..."
}

Example

curl -X POST https://api.turbinefi.com/api/v1/relayer/ctf-redemption \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chainId": 137,
    "owner": "0xYourAddress",
    "collateralToken": "0xUSDCAddress",
    "parentCollectionId": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "conditionId": "0xConditionId",
    "indexSets": ["1", "2"],
    "deadline": "1735689600",
    "v": 27,
    "r": "0x...",
    "s": "0x...",
    "marketAddress": "0xMarketContract"
  }'

Batch CTF Redemption

Redeem positions across multiple markets in a single transaction using Multicall3. More gas-efficient than individual redemptions.

POST /api/v1/relayer/batch-ctf-redemption

Request Body

{
  "chainId": 137,
  "owner": "0xYourAddress...",
  "redemptions": [
    {
      "marketAddress": "0xMarketA...",
      "collateralToken": "0xUSDCAddress...",
      "parentCollectionId": "0x000...000",
      "conditionId": "0xConditionIdA...",
      "indexSets": ["1", "2"],
      "deadline": "1735689600",
      "v": 27,
      "r": "0x...",
      "s": "0x..."
    },
    {
      "marketAddress": "0xMarketB...",
      "collateralToken": "0xUSDCAddress...",
      "parentCollectionId": "0x000...000",
      "conditionId": "0xConditionIdB...",
      "indexSets": ["1", "2"],
      "deadline": "1735689600",
      "v": 28,
      "r": "0x...",
      "s": "0x..."
    }
  ]
}

Field	Type	Description
chainId	int64	Chain ID (e.g., 137)
owner	address	Your wallet address
redemptions	array	Array of individual redemption data (see CTF Redemption fields above, plus marketAddress required)

Response

{
  "success": true,
  "txHash": "0xTransactionHash...",
  "status": "pending"
}

Field	Type	Description
success	bool	Whether the transaction was submitted
txHash	string	Transaction hash
status	string	"pending" or "confirmed"

Example

curl -X POST https://api.turbinefi.com/api/v1/relayer/batch-ctf-redemption \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chainId": 137,
    "owner": "0xYourAddress",
    "redemptions": [
      {
        "marketAddress": "0xMarketA",
        "collateralToken": "0xUSDC",
        "parentCollectionId": "0x000...000",
        "conditionId": "0xConditionA",
        "indexSets": ["1", "2"],
        "deadline": "1735689600",
        "v": 27,
        "r": "0x...",
        "s": "0x..."
      }
    ]
  }'

Propose Resolution

Submit a resolution proposal for an expired market. The proposer asserts an outcome via the UMA Optimistic Oracle with a bond.

POST /api/v1/relayer/propose-resolution

Request Body

{
  "chainId": 137,
  "marketAddress": "0xMarketContract...",
  "proposer": "0xYourAddress...",
  "outcome": true,
  "deadline": "1735689600",
  "v": 27,
  "r": "0x...",
  "s": "0x...",
  "bondPermitDeadline": "1735689600",
  "bondV": 27,
  "bondR": "0x...",
  "bondS": "0x..."
}

Field	Type	Description
chainId	int64	Chain ID (e.g., 137)
marketAddress	address	Market contract address
proposer	address	Your wallet address
outcome	bool	Proposed outcome: true = YES, false = NO
deadline	string	Permit expiration (Unix timestamp as string)
v	uint8	Signature component
r	string	Signature component (32 bytes hex)
s	string	Signature component (32 bytes hex)
bondPermitDeadline	string	Bond USDC permit deadline (optional, omit for testnet)
bondV	uint8	Bond permit signature component (optional)
bondR	string	Bond permit signature component (optional)
bondS	string	Bond permit signature component (optional)

The bond permit fields are required on mainnet where the proposer must post a UMA bond in USDC. On testnet, these can be omitted.

Response

{
  "success": true,
  "tx_hash": "0xTransactionHash..."
}

Example

curl -X POST https://api.turbinefi.com/api/v1/relayer/propose-resolution \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chainId": 137,
    "marketAddress": "0xMarketContract",
    "proposer": "0xYourAddress",
    "outcome": true,
    "deadline": "1735689600",
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }'

Settle Market

Settle a market after the UMA oracle dispute window has passed (2 hours). Finalizes the winning outcome and enables redemptions.

POST /api/v1/relayer/settle-market

Request Body

{
  "chainId": 137,
  "marketAddress": "0xMarketContract...",
  "settler": "0xYourAddress...",
  "deadline": "1735689600",
  "v": 27,
  "r": "0x...",
  "s": "0x...",
  "winningOutcome": 0
}

Field	Type	Description
chainId	int64	Chain ID (e.g., 137)
marketAddress	address	Market contract address
settler	address	Your wallet address
deadline	string	Permit expiration (Unix timestamp as string)
v	uint8	Signature component
r	string	Signature component (32 bytes hex)
s	string	Signature component (32 bytes hex)
winningOutcome	uint8	0 = YES, 1 = NO

Response

{
  "success": true,
  "tx_hash": "0xTransactionHash..."
}

Example

curl -X POST https://api.turbinefi.com/api/v1/relayer/settle-market \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chainId": 137,
    "marketAddress": "0xMarketContract",
    "settler": "0xYourAddress",
    "deadline": "1735689600",
    "v": 27,
    "r": "0x...",
    "s": "0x...",
    "winningOutcome": 0
  }'

Get Pending Claims

Returns CTF redemptions waiting for on-chain confirmation.

GET /api/v1/pending-claims

Response

{
  "pendingClaims": [
    {
      "txHash": "0x...",
      "userAddress": "0x...",
      "marketAddress": "0x...",
      "marketId": "0x...",
      "payout": 50000000,
      "winningOutcome": 0,
      "submittedAt": 1735689000
    }
  ],
  "count": 1
}

Field	Type	Description
txHash	string	Redemption transaction hash
userAddress	address	User who redeemed
marketAddress	address	Market contract address
marketId	string	Market identifier
payout	int64	Expected payout in USDC (6 decimals). 50000000 = $50
winningOutcome	int	0 = YES, 1 = NO
submittedAt	int64	Unix timestamp when redemption was submitted

Example

curl "https://api.turbinefi.com/api/v1/pending-claims"

Get Failed Claims

Returns CTF redemptions that failed on-chain.

GET /api/v1/failed-claims

Response

{
  "failedClaims": [
    {
      "txHash": "0x...",
      "userAddress": "0x...",
      "marketAddress": "0x...",
      "marketId": "0x...",
      "payout": 50000000,
      "winningOutcome": 0,
      "submittedAt": 1735689000
    }
  ],
  "count": 1
}

The response fields are the same as pending claims.

Example

curl "https://api.turbinefi.com/api/v1/failed-claims"

Error Responses

All relayer endpoints return the same error format:

{
  "success": false,
  "error": "Description of what went wrong"
}

Common errors

Error	Description
Invalid request body	Malformed JSON
Invalid address format	Address is not valid hex
Invalid signature format	r and s must be 66 characters (0x + 64 hex)
No relayer configured for chain	Chain ID is not supported