{ "openapi": "3.1.0", "info": { "title": "OpenAds advertiser agent API", "version": "1.0.0", "description": "Advertiser API for campaign preparation, approved funding and result queries. prepare_campaign, launch_campaign and get_campaign are local client functions, not HTTP routes. Read instructions.txt and integration.txt for approval, payment and retry rules." }, "servers": [ { "url": "https://api.openads.world" } ], "security": [ { "V2SessionCookie": [] }, { "V2SessionHeader": [] } ], "paths": { "/api/v2/auth/challenge": { "get": { "operationId": "createAuthChallenge", "tags": [ "Auth" ], "security": [], "x-openads-feature-gates": [ "V2_API_ENABLED" ], "parameters": [ { "$ref": "#/components/parameters/WalletQuery" } ], "responses": { "200": { "description": "Five-minute wallet login challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthChallenge" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/auth/session": { "post": { "operationId": "createAuthSession", "tags": [ "Auth" ], "security": [], "x-openads-feature-gates": [ "V2_API_ENABLED" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "24-hour HTTP-only session", "headers": { "Set-Cookie": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteAuthSession", "tags": [ "Auth" ], "x-openads-feature-gates": [ "V2_API_ENABLED" ], "responses": { "204": { "description": "Session revoked" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/campaigns/policy": { "get": { "operationId": "getCampaignPolicy", "tags": [ "Advertise" ], "description": "Small account-specific policy query only: pricing, selectable channels and active payment chains. No campaigns, ledger aggregation, chain RPC or funding recovery. Private/no-store; account 120/min and network 300/min.", "x-openads-feature-gates": [ "V2_API_ENABLED" ], "responses": { "200": { "description": "Current campaign preparation policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPolicy" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/campaigns": { "post": { "operationId": "createCampaignDraft", "tags": [ "Advertise" ], "x-openads-feature-gates": [ "V2_API_ENABLED", "V2_COMMANDS_ENABLED" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } } }, "responses": { "201": { "description": "Campaign draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignView" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Campaign metadata body is limited to 32 KiB (images use the assets route). Network preparation limit 120/min, account preparation limit 60/min, draft creation limit 30/hour. Same idempotency key must be used on retries." } }, "/api/v2/campaigns/{id}": { "get": { "operationId": "getCampaign", "tags": [ "Advertise" ], "x-openads-feature-gates": [ "V2_API_ENABLED" ], "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "Canonical Campaign view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignView" } } } }, "404": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/campaigns/{id}/commands/{command}": { "post": { "operationId": "commandCampaign", "tags": [ "Advertise" ], "x-openads-feature-gates": [ "V2_API_ENABLED", "V2_COMMANDS_ENABLED" ], "parameters": [ { "$ref": "#/components/parameters/ResourceId" }, { "name": "command", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CampaignCommand" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCommandRequest" } } } }, "responses": { "200": { "description": "Updated Campaign view or Review & Launch result", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CampaignView" }, { "$ref": "#/components/schemas/ReviewLaunchResponse" } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Metadata body is limited to 32 KiB. save-draft and submit-review share preparation limits: network 120/min and account 60/min. Lifecycle commands keep their existing protections. Expired managed images prevent launch before funding." } }, "/api/v2/assets": { "post": { "operationId": "uploadCampaignAsset", "tags": [ "Advertise" ], "x-openads-feature-gates": [ "V2_API_ENABLED", "V2_COMMANDS_ENABLED" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAssetUploadRequest" } } } }, "responses": { "201": { "description": "Content-addressed Campaign image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAsset" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/funding/submissions": { "post": { "operationId": "recordFundingSubmission", "tags": [ "Settlement" ], "x-openads-feature-gates": [ "V2_API_ENABLED", "V2_FUNDING_SYNC_ENABLED" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingReceiptRequest" } } } }, "responses": { "202": { "description": "Broadcast recorded; observation and final accounting continue automatically", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingSubmissionResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "V2SessionCookie": { "type": "apiKey", "in": "cookie", "name": "openads_v2_session" }, "V2SessionHeader": { "type": "apiKey", "in": "header", "name": "x-openads-v2-session", "description": "Use the raw openads_v2_session cookie value from Set-Cookie, not the JSON access_token." } }, "parameters": { "WalletQuery": { "name": "wallet", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Wallet" } }, "ResourceId": { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } }, "schemas": { "Wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "AuthChallenge": { "type": "object", "additionalProperties": false, "required": [ "schema", "challenge", "message", "expires_at" ], "properties": { "schema": { "const": "openads.auth-challenge/2.0" }, "challenge": { "type": "string" }, "message": { "type": "string" }, "expires_at": { "$ref": "#/components/schemas/DateTime" } } }, "DateTime": { "type": "string", "format": "date-time" }, "Error": { "type": "object", "additionalProperties": false, "required": [ "schema", "error", "message" ], "properties": { "schema": { "const": "openads.error/2.0" }, "error": { "type": "string" }, "message": { "type": "string" }, "next_action": { "type": "string", "description": "Shared website/SDK recovery instruction. Never start a second payment to recover an existing transaction." }, "retryable": { "type": "boolean", "description": "True only for a bounded retry of the same operation. False requires user/operator action or current-state review." }, "retry_after": { "type": [ "string", "null" ], "description": "Minimum delay in seconds when provided; HTTP Retry-After takes precedence. Unknown wait durations remain null." } } }, "LoginRequest": { "type": "object", "additionalProperties": false, "required": [ "challenge", "signature" ], "properties": { "challenge": { "type": "string" }, "signature": { "type": "string" } } }, "Session": { "type": "object", "additionalProperties": false, "required": [ "schema", "account_id", "actor_wallet", "expires_at" ], "properties": { "schema": { "const": "openads.session/2.0" }, "account_id": { "$ref": "#/components/schemas/Uuid" }, "actor_wallet": { "$ref": "#/components/schemas/Wallet" }, "expires_at": { "$ref": "#/components/schemas/DateTime" }, "access_token": { "type": "string", "description": "Separate site-access token, NOT a V2 API session token. Keep private. For API authentication preserve the openads_v2_session cookie from Set-Cookie." } } }, "Uuid": { "type": "string", "format": "uuid" }, "CampaignPolicy": { "type": "object", "required": [ "schema", "capabilities", "available_chain_ids" ], "properties": { "schema": { "const": "openads.campaign-policy/1.0" }, "available_chain_ids": { "type": "array", "uniqueItems": true, "maxItems": 2, "items": { "enum": [ 5042, 8453 ] } }, "capabilities": { "type": "object", "required": [ "web", "shares", "reward" ], "properties": { "web": { "type": "object", "required": [ "minimum_cpm", "minimum_cpm_default" ], "properties": { "minimum_cpm": { "type": "object", "additionalProperties": { "type": "number", "exclusiveMinimum": 0 } }, "minimum_cpm_default": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "shares": { "oneOf": [ { "$ref": "#/components/schemas/ShareAdvertiserCapability" }, { "type": "object", "required": [ "runtime_state", "selectable" ], "properties": { "runtime_state": { "const": "DISABLED" }, "selectable": { "const": false } }, "additionalProperties": false }, { "type": "null" } ] }, "reward": { "oneOf": [ { "$ref": "#/components/schemas/RewardAdvertiserCapability" }, { "type": "object", "required": [ "runtime_state", "selectable" ], "properties": { "runtime_state": { "const": "DISABLED" }, "selectable": { "const": false } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "ShareAdvertiserCapability": { "type": "object", "additionalProperties": false, "required": [ "runtime_state", "selectable", "recommended_cpc_micro", "recommended_budget_bps" ], "properties": { "runtime_state": { "enum": [ "OFF", "SHADOW", "PILOT", "LIVE", "HOLD" ] }, "selectable": { "type": "boolean" }, "recommended_cpc_micro": { "oneOf": [ { "$ref": "#/components/schemas/PositiveMicroUsdc" }, { "type": "null" } ] }, "recommended_budget_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "pricing_policy_version": { "type": [ "integer", "null" ], "minimum": 1 } } }, "PositiveMicroUsdc": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "RewardAdvertiserCapability": { "type": "object", "additionalProperties": false, "required": [ "runtime_state", "selectable", "recommended_base_reward_micro", "recommended_budget_bps", "telegram_bonus_bps", "platform_bps", "challenge_ttl_seconds", "same_campaign_cooldown_seconds", "maximum_campaign_allocation_micro" ], "properties": { "runtime_state": { "enum": [ "OFF", "SHADOW", "PILOT", "LIVE", "HOLD" ] }, "selectable": { "type": "boolean" }, "recommended_base_reward_micro": { "oneOf": [ { "$ref": "#/components/schemas/PositiveMicroUsdc" }, { "type": "null" } ] }, "recommended_budget_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "telegram_bonus_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "platform_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "challenge_ttl_seconds": { "type": "integer", "minimum": 5 }, "same_campaign_cooldown_seconds": { "type": "integer", "minimum": 3600, "maximum": 3600 }, "maximum_campaign_allocation_micro": { "$ref": "#/components/schemas/PositiveMicroUsdc" }, "pricing_policy_version": { "type": [ "integer", "null" ], "minimum": 1 }, "fixed_platform_fee_micro": { "oneOf": [ { "$ref": "#/components/schemas/MicroUsdc" }, { "type": "null" } ] }, "recommended_cost_per_completion_micro": { "oneOf": [ { "$ref": "#/components/schemas/PositiveMicroUsdc" }, { "type": "null" } ] } } }, "CreateCampaignRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "draft_plan", "idempotency_key" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "draft_plan": { "$ref": "#/components/schemas/JsonObject" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKey" } } }, "JsonObject": { "type": "object", "additionalProperties": true }, "IdempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128 }, "CampaignView": { "allOf": [ { "$ref": "#/components/schemas/VersionedView" }, { "type": "object", "required": [ "name", "status", "effective_status", "active_surfaces", "total_surfaces", "draft_plan", "draft_plan_version", "surfaces", "settlement" ], "properties": { "schema": { "const": "openads.campaign/2.0" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/CampaignLifecycle" }, "effective_status": { "type": "string" }, "active_surfaces": { "type": "integer", "minimum": 0 }, "total_surfaces": { "type": "integer", "minimum": 0 }, "draft_plan": { "$ref": "#/components/schemas/JsonObject" }, "draft_plan_version": { "type": "integer", "minimum": 1 }, "surfaces": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "funding": { "oneOf": [ { "$ref": "#/components/schemas/FundingIntentView" }, { "type": "null" } ] }, "settlement": { "oneOf": [ { "$ref": "#/components/schemas/CampaignSettlement" }, { "type": "null" } ] }, "assets_expired": { "type": "boolean", "description": "Known temporary images have expired; reprepare before payment." } } } ] }, "VersionedView": { "type": "object", "required": [ "schema", "id", "version", "as_of", "updated_at" ], "properties": { "schema": { "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "version": { "type": "integer", "minimum": 0 }, "as_of": { "$ref": "#/components/schemas/DateTime" }, "updated_at": { "$ref": "#/components/schemas/DateTime" } } }, "CampaignLifecycle": { "enum": [ "DRAFT", "ACTIVE", "PAUSED", "CLOSING", "SETTLED", "ARCHIVED", "REVOKED" ] }, "FundingIntentView": { "type": "object", "additionalProperties": true, "required": [ "mode" ], "properties": { "mode": { "enum": [ "NONE", "READY_FROM_AVAILABLE", "WAITING_FOR_DEPOSIT" ] }, "intent_id": { "$ref": "#/components/schemas/Uuid" }, "campaign_id": { "$ref": "#/components/schemas/Uuid" }, "status": { "enum": [ "PENDING", "COMPLETED", "CANCELLED", "EXPIRED" ] }, "chain_id": { "type": "integer", "minimum": 1 }, "vault_version": { "type": "integer", "minimum": 1 }, "vault_address": { "$ref": "#/components/schemas/Wallet" }, "token_address": { "$ref": "#/components/schemas/Wallet" }, "required_total_micro": { "$ref": "#/components/schemas/PositiveMicroUsdc" }, "reserved_micro": { "$ref": "#/components/schemas/MicroUsdc" }, "confirmed_received_micro": { "$ref": "#/components/schemas/MicroUsdc" }, "remaining_shortfall_micro": { "$ref": "#/components/schemas/MicroUsdc" }, "funding_ref": { "$ref": "#/components/schemas/Bytes32" }, "launch_plan_hash": { "$ref": "#/components/schemas/Bytes32" }, "created_block": { "type": "integer", "minimum": 0 }, "last_checked_block": { "type": [ "integer", "null" ], "minimum": 0 }, "expires_at": { "$ref": "#/components/schemas/DateTime" }, "recovery_until": { "$ref": "#/components/schemas/DateTime" }, "replay": { "type": "boolean" } } }, "MicroUsdc": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer micro-USDC. Never a JSON number." }, "Bytes32": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "CampaignSettlement": { "type": "object", "additionalProperties": false, "required": [ "vault_version", "chain_id", "vault_address", "token_address" ], "properties": { "vault_version": { "type": "integer", "minimum": 1 }, "chain_id": { "enum": [ 8453, 5042 ] }, "vault_address": { "$ref": "#/components/schemas/Wallet" }, "token_address": { "$ref": "#/components/schemas/Wallet" } } }, "CampaignCommand": { "enum": [ "save-draft", "submit-review", "review-launch" ] }, "CampaignCommandRequest": { "type": "object", "required": [ "target_version", "idempotency_key" ], "properties": { "target_version": { "type": "integer", "minimum": 1 }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKey" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "draft_plan": { "$ref": "#/components/schemas/JsonObject" }, "funding_ref": { "$ref": "#/components/schemas/Bytes32" }, "chain_id": { "enum": [ 8453, 5042 ] }, "allocations": { "type": "array", "minItems": 1, "maxItems": 7, "items": { "$ref": "#/components/schemas/ReviewLaunchAllocation" } }, "signature": { "$ref": "#/components/schemas/CommandSignature" } } }, "ReviewLaunchAllocation": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "surface", "format", "amount_micro" ], "properties": { "surface": { "const": "WEB" }, "format": { "$ref": "#/components/schemas/WebFormat" }, "amount_micro": { "$ref": "#/components/schemas/PositiveMicroUsdc" } } }, { "type": "object", "additionalProperties": false, "required": [ "surface", "format", "amount_micro" ], "properties": { "surface": { "const": "SHARE" }, "format": { "const": "SHARE_CARD" }, "amount_micro": { "$ref": "#/components/schemas/PositiveMicroUsdc" } } }, { "type": "object", "additionalProperties": false, "required": [ "surface", "format", "amount_micro" ], "properties": { "surface": { "const": "REWARD" }, "format": { "const": "REWARDED_VISIT" }, "amount_micro": { "$ref": "#/components/schemas/PositiveMicroUsdc" } } } ] }, "WebFormat": { "enum": [ "320X50_TOP", "320X50", "300X250", "64X64" ] }, "CommandSignature": { "type": "object", "additionalProperties": false, "required": [ "signature", "issued_at", "expires_at" ], "properties": { "signature": { "type": "string" }, "issued_at": { "$ref": "#/components/schemas/DateTime" }, "expires_at": { "$ref": "#/components/schemas/DateTime" } } }, "ReviewLaunchResponse": { "type": "object", "additionalProperties": false, "required": [ "schema", "outcome", "campaign", "approved_launch_plan", "funding", "replay" ], "properties": { "schema": { "const": "openads.review-launch/2.0" }, "outcome": { "enum": [ "ALL_READY", "PARTIAL_READY", "WAITING_FOR_REVIEW", "NEEDS_CHANGES" ] }, "campaign": { "$ref": "#/components/schemas/CampaignView" }, "approved_launch_plan": { "type": "object", "required": [ "allocations" ], "properties": { "launch_plan_hash": { "$ref": "#/components/schemas/Bytes32" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovedLaunchAllocation" } } } }, "funding": { "$ref": "#/components/schemas/FundingIntentView" }, "replay": { "type": "boolean" } } }, "ApprovedLaunchAllocation": { "type": "object", "additionalProperties": false, "required": [ "surface_term_id", "delivery_term_version_id", "creative_variant_id", "amount_micro" ], "properties": { "surface_term_id": { "$ref": "#/components/schemas/Uuid" }, "delivery_term_version_id": { "$ref": "#/components/schemas/Uuid" }, "creative_variant_id": { "$ref": "#/components/schemas/Uuid" }, "amount_micro": { "$ref": "#/components/schemas/PositiveMicroUsdc" } } }, "CampaignAssetUploadRequest": { "type": "object", "additionalProperties": false, "required": [ "campaign_id", "format", "data_url" ], "properties": { "campaign_id": { "$ref": "#/components/schemas/Uuid" }, "format": { "$ref": "#/components/schemas/CampaignAssetFormat" }, "data_url": { "type": "string", "pattern": "^data:image/(?:png|jpeg|webp|gif);base64,[A-Za-z0-9+/]+={0,2}$", "description": "Complete image data URL. PNG/JPEG/WebP <=3 MiB; GIF <=1 MiB. Server also validates image content, dimensions and animation limits." } } }, "CampaignAssetFormat": { "enum": [ "320X50_TOP", "320X50", "300X250", "64X64", "SHARE_CARD", "REWARDED_VISIT" ] }, "CampaignAsset": { "type": "object", "additionalProperties": false, "required": [ "schema", "campaign_id", "format", "asset_url", "sha256" ], "properties": { "schema": { "const": "openads.campaign-asset/2.0" }, "campaign_id": { "$ref": "#/components/schemas/Uuid" }, "format": { "$ref": "#/components/schemas/CampaignAssetFormat" }, "asset_url": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "FundingReceiptRequest": { "type": "object", "additionalProperties": false, "required": [ "intent_id", "tx_hash" ], "properties": { "intent_id": { "$ref": "#/components/schemas/Uuid" }, "tx_hash": { "$ref": "#/components/schemas/TxHash" } } }, "TxHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "FundingSubmissionResponse": { "type": "object", "additionalProperties": true, "required": [ "schema", "submission_id", "intent_id", "tx_hash", "status" ], "properties": { "schema": { "const": "openads.funding-submission/2.0" }, "submission_id": { "$ref": "#/components/schemas/Uuid" }, "intent_id": { "$ref": "#/components/schemas/Uuid" }, "tx_hash": { "$ref": "#/components/schemas/TxHash" }, "status": { "enum": [ "SUBMITTED", "OBSERVED", "FINALIZED", "REORGED", "FAILED" ] } } } }, "responses": { "Error": { "description": "Versioned fail-closed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }