opporDocumentation
Marketplace
ReferenceAPI overview
Reference

API overview

Integrate campaign discovery, wallet authentication, and transaction preparation.

Request conventions

The API is served under /v1. JSON responses use typed fields. Campaign IDs and entry IDs are UUIDs; token quantities are canonical decimal strings in base units.

GET requests retrieve state. Session-authenticated mutations require the session cookie, X-CSRF-Token, an allowed Origin, and Idempotency-Key. Keep the CSRF token in memory.

HTTP
GET /v1/campaigns?limit=25&sort=ending
Accept: application/json

Wallet authentication

Deployed contract wallets use EIP-1271 signature validation. Counterfactual wallets using EIP-6492 are not supported. Changing or revoking a contract-wallet signature can invalidate the session.

  1. POST /auth/challenge with wallet and chain_id.

  2. Sign the exact returned message using the selected wallet.

  3. POST /auth/verify with message and signature.

  4. Send credentials on authenticated requests and the returned CSRF token on mutations.

JSON
{
  "wallet": "<wallet-address>",
  "chain_id": "<configured-chain-id>"
}

Core endpoints

EndpointPurpose
GET /campaignsPaginated public discovery; filters and newest/ending sort.
GET /campaigns/:idCampaign configuration and ordered tasks.
POST /campaignsCreate a private campaign draft.
POST /campaigns/:id/entriesRegister the authenticated payout wallet.
PUT /campaigns/:id/my-entry/submissions/:task_idSave versioned task evidence.
POST /campaigns/:id/my-entry/submitSubmit the current entry for review.
GET /campaigns/:id/allocations/:walletRetrieve allocations and claim proofs.

Prepared transactions

Prepare endpoints return an unsigned transaction with chain_id, to, data, value, expected_sender, intent, and expires_at. The caller checks the payload and asks the designated wallet to execute it.

Creation, funding, activation, finalization, claiming, cancellation, and sweeping each have a prepare endpoint. Funding also returns required approvals. Confirm approvals and prepare funding again before execution.

POST /campaigns/:id/transactions records a tracking hint. Authoritative confirmation comes from the indexer’s verified escrow events.

Versioning and retries

Versioned mutations carry expected_version. If state has changed, refresh and inspect it before repeating the action.

For an ambiguous network failure or timeout, reuse the same idempotency key with the exact original payload. Do not retry a rejected business rule blindly.

HTTP
X-CSRF-Token: <session-csrf-token>
Idempotency-Key: <unique-request-key>
Content-Type: application/json

Error responses

400 indicates an invalid request, 401 an unauthenticated session, 403 denied access, 404 an unavailable resource, 409 a state or version conflict, 422 business validation, and 429 a rate limit. Dependency failures use 503 or 504.

JSON
{
  "error": {
    "code": "STALE_VERSION",
    "message": "Refresh the campaign before editing.",
    "request_id": "<request-reference>"
  }
}