{
    "openapi": "3.1.0",
    "info": {
        "title": "agents.u.cash",
        "version": "0.1.0",
        "description": "Agent + merchant product surface for the 402 Online Protocol \u2014 multi-coin, non-custodial. Reference implementation: U.CASH Pay."
    },
    "servers": [
        {
            "url": "https://agents.u.cash"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key"
            }
        },
        "schemas": {
            "Signup": {
                "type": "object",
                "required": [
                    "email",
                    "password"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "password": {
                        "type": "string",
                        "minLength": 8
                    },
                    "primary_wallet": {
                        "type": "string"
                    }
                }
            },
            "Wallet": {
                "type": "object",
                "required": [
                    "asset",
                    "address"
                ],
                "properties": {
                    "asset": {
                        "type": "string",
                        "description": "cryptocurrency code, e.g. btc, eth, sol"
                    },
                    "address": {
                        "type": "string"
                    }
                }
            },
            "Resource": {
                "type": "object",
                "required": [
                    "amount"
                ],
                "properties": {
                    "amount": {
                        "type": "number",
                        "description": "fiat price, e.g. 0.01"
                    },
                    "currency": {
                        "type": "string",
                        "default": "USD"
                    },
                    "accepted_assets": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "defaults to all configured wallets"
                    },
                    "webhook_url": {
                        "type": "string",
                        "description": "notified on settlement"
                    }
                }
            }
        }
    },
    "paths": {
        "/v1/signup": {
            "post": {
                "summary": "Register an agent account (wallet-first; returns the api_key immediately)",
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Signup"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "api_key + activation instructions"
                    },
                    "400": {
                        "description": "validation error"
                    }
                }
            }
        },
        "/v1/top-up": {
            "post": {
                "summary": "Create a credit top-up checkout ($1 min; activates the account on confirmation)",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 1
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "checkout url"
                    }
                }
            }
        },
        "/v1/agent": {
            "get": {
                "summary": "Account snapshot: balance, activation, wallets, webhook URL, earnings summary",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "account"
                    },
                    "402": {
                        "description": "agent not activated"
                    }
                }
            },
            "post": {
                "summary": "Set the webhook URL notified on settlement {webhook_url}",
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/v1/wallets": {
            "post": {
                "summary": "Set your own receive address for an asset (where buyer funds land)",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Wallet"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "stored wallet"
                    }
                }
            }
        },
        "/v1/resources": {
            "post": {
                "summary": "Create a priced resource (accepts the agent's configured wallets by default)",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Resource"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "res_id"
                    }
                }
            },
            "get": {
                "summary": "List the agent's resources, or fetch one with ?res_id= (each carries a settled flag)",
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/v1/challenge": {
            "post": {
                "summary": "Build the multi-coin 402 accepts[] for a resource {res_id}",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "accepts[]"
                    }
                }
            }
        },
        "/v1/settlements": {
            "get": {
                "summary": "The agent's earnings log (settled + underpaid resource payments)",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "settlements"
                    }
                }
            }
        },
        "/v1/verify": {
            "post": {
                "summary": "Verify + settle a detect payment {challengeId, hash}",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "settled | pending"
                    },
                    "402": {
                        "description": "agent not activated"
                    }
                }
            }
        },
        "/r/{id}": {
            "get": {
                "summary": "The 402 door \u2014 returns HTTP 402 + accepts[] (public, no key)",
                "security": [],
                "responses": {
                    "402": {
                        "description": "accepts[]"
                    },
                    "200": {
                        "description": "already settled"
                    }
                }
            }
        }
    }
}