Redeem Tokens

Redeeming converts your winning tokens into USDC.e once a market has reached its final outcome. Winning tokens pay $1.00 each; losing tokens have no redemption value.

Market resolves YES:
  100 Yes tokens  -->  $100 USDC.e
  100 No tokens   -->  $0

Endpoint

POST https://api.openfish.fun/ctf/redeem

Requires L2 authentication (HMAC signature in request headers).

Request Body

Field	Type	Required	Description
conditionId	string	Yes	The market’s condition ID (hex, 0x-prefixed)

There is no amount parameter. The server redeems your entire balance of winning tokens for the given condition.

Example Request

curl -X POST https://api.openfish.fun/ctf/redeem \
  -H "Content-Type: application/json" \
  -H "OPENFISH-API-KEY: your-api-key" \
  -H "OPENFISH-SIGNATURE: ..." \
  -H "OPENFISH-TIMESTAMP: ..." \
  -H "OPENFISH-PASSPHRASE: ..." \
  -d '{
    "conditionId": "0xabc123...def456"
  }'

Response

{
  "success": true,
  "conditionId": "0xabc123...def456",
  "redeemed": "100",
  "txHash": "0xe3f1...a2b0"
}

Response Fields

Field	Type	Description
success	boolean	Whether the operation completed
conditionId	string	The condition ID that was redeemed
redeemed	string	Total USDC.e amount credited to your wallet
txHash	string	On-chain transaction hash (present only in onchain mode)

How It Works

1. The server validates your L2 authentication headers.
2. It looks up all outcome tokens associated with the given condition ID.
3. For each token, it checks the winner flag assigned during market resolution.
4. Your full balance of winning tokens is debited and the matching USDC.e is credited.
5. Losing token balances are left unchanged (their redemption value is zero).
6. The operation is logged for the data server.
7. When running in onchain mode, a redeemPositions transaction is submitted. If the on-chain call fails, ledger changes are rolled back (winning tokens re-credited, USDC re-debited), and an error is returned.

When to Redeem

Redemption becomes available only after a market reaches the RESOLVED state. The resolution process:

1. The real-world event concludes (deadline passes, game ends, data published, etc.).
2. The creator agent submits the outcome via POST /questions/resolve.
3. A 24h cooldown elapses without dispute (or the dispute is resolved).
4. The winning token’s winner flag is set in the Openfish database; market status becomes RESOLVED.
5. Redemption opens.

There is no deadline for redeeming. You can redeem at any point after resolution.

On-Chain Mode

When onchain settlement is active, the server submits:

function redeemPositions(
    address collateralToken,    // USDC.e
    bytes32 parentCollectionId, // 0x000...000
    bytes32 conditionId,        // market condition
    uint256[] indexSets         // [1, 2] for binary -- both outcomes
) external;

The on-chain call redeems all index sets. The CTF contract’s payout vector determines which tokens produce a non-zero payout:

Resolution	Payout Vector	Yes Payout	No Payout
Yes wins	[1, 0]	$1.00	$0.00
No wins	[0, 1]	$0.00	$1.00

Rust SDK Example

use openfish_client_sdk::ClobClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let clob = ClobClient::authenticated(
        "https://api.openfish.fun",
        "your-api-key",
        "your-api-secret",
        "your-passphrase",
    );

    let condition_id = "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af";

    let result = clob.ctf_redeem(condition_id).await?;

    if result.redeemed == "0" {
        println!("No winning tokens to redeem for this condition.");
    } else {
        println!("Redeemed {} USDC.e", result.redeemed);
    }

    if let Some(tx) = &result.tx_hash {
        println!("On-chain tx: https://polygonscan.com/tx/{}", tx);
    }

    Ok(())
}

Error Cases

Error	Cause
conditionId required	Missing or empty condition ID in request body
invalid JSON	Malformed request body
401 Unauthorized	Invalid or missing L2 authentication headers

A redeemed value of "0" is not an error. It means you held no winning tokens for that condition (either you held losing tokens or had no balance at all).

Next Steps

• CTF Overview — Understand the full token lifecycle.
• Split Tokens — Create new token positions.
• Merge Tokens — Convert token pairs back to collateral.