{
  "openapi": "3.1.0",
  "info": {
    "title": "Tragent API",
    "version": "1.2.2",
    "summary": "Research answers paid per call, and accounts agents buy: their own Tragent and wallet on Base.",
    "description": "No account, key or sign-up. Each answer is paid for over HTTP, one of two ways. In USDC on Base with the x402 protocol (version 2, scheme exact): send the request, receive 402 with a PAYMENT-REQUIRED header, sign the payment it asks for, and send the request again with a PAYMENT-SIGNATURE header. Or by card through a Link wallet with the Machine Payments Protocol (method stripe, intent charge): send the request, receive 402 with a WWW-Authenticate: Payment challenge, and send the request again with an Authorization: Payment credential. Research only, not financial advice. An agent can also buy an account of its own (POST /api/v1/x402/plan or /api/v1/mpp/plan, paid first): its own Tragent, which researches, decides and trades on Base within the account's rules, its own wallet owned by a P-256 key the buyer keeps, and the account API at /api/v1/agent/*, with API keys issued to requests that key signs.",
    "x-guidance": "Ask one question per call with the body {\"question\": \"...\"}. POST /api/v1/x402/ask to pay in USDC on Base (x402), or POST /api/v1/mpp/ask to pay by card through a Link wallet (Machine Payments Protocol, method stripe). The answer is the same on both. To act and not only ask, buy an account: POST /api/v1/x402/plan with {\"ownerKey\": \"<base64 SPKI P-256 public key>\", \"sendTo\": \"0x...\"}, then POST /api/v1/agent/keys with a request the owner key signs, then call /api/v1/agent/ask with the key as a Bearer token.",
    "termsOfService": "https://tragent.fyi/terms-of-service#api",
    "contact": {
      "name": "Tragent support",
      "email": "support@tragent.fyi",
      "url": "https://tragent.fyi/developers"
    }
  },
  "servers": [
    {
      "url": "https://tragent.fyi"
    }
  ],
  "externalDocs": {
    "description": "Developer reference",
    "url": "https://tragent.fyi/developers"
  },
  "x-service-info": {
    "categories": [
      "blockchain",
      "data"
    ],
    "docs": {
      "homepage": "https://tragent.fyi/developers",
      "apiReference": "https://tragent.fyi/openapi.json",
      "llms": "https://tragent.fyi/llms.txt"
    }
  },
  "paths": {
    "/api/v1/x402/ask": {
      "post": {
        "operationId": "ask",
        "summary": "Ask one question and pay for the answer in USDC",
        "description": "Covers live and past token prices, on-chain activity (transfers, swaps, large holders, wallet balances and positions) and DEX markets (pairs, liquidity, volume, trending tokens). News, macro data and derivatives are not covered yet.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.250000"
          },
          "protocols": [
            {
              "x402": {
                "x402Version": 2,
                "scheme": "exact",
                "network": "eip155:8453",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "assetSymbol": "USDC"
              }
            }
          ]
        },
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "description": "The signed x402 payment, base64 JSON. Omit it on the first request to receive the payment requirement.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Question"
              },
              "example": {
                "question": "What is ETH trading at, and what does on-chain activity show today?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer. The PAYMENT-RESPONSE header names the transaction that collected the payment.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "The settlement, base64 JSON: success, transaction, network, payer.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Answer"
                }
              }
            }
          },
          "400": {
            "description": "The body is not one question of 1 to 2,000 characters. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required, or the payment was not accepted. The PAYMENT-REQUIRED header holds what to pay; its error field says why a payment was not accepted.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "The payment requirement, base64 JSON (x402 version 2).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Payments from this wallet are not accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "in_progress: this request is already being answered, send it again after Retry-After. payment_reused: this payment was made for another question.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "answer_expired: more than 15 minutes have passed since this payment was first sent, and its answer is no longer kept. payment_refunded: the request could not be answered and its payment is being refunded. Send the request with a new payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this wallet or address. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "settlement_pending: the payment is being confirmed, send the same request again after Retry-After and do not sign a new payment. answer_failed: the answer could not be produced; the message says whether the payment was kept for a retry. busy: at a limit, out of time or paused; the message says whether the payment was kept. payment_check_unavailable: try later, nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mpp/ask": {
      "post": {
        "operationId": "askByCard",
        "summary": "Ask one question and pay for the answer by card",
        "description": "The same question and the same answer as /api/v1/x402/ask, paid by card or Link balance through a Link wallet with the Machine Payments Protocol. The amount is held on the card when the payment is sent and charged only when the answer is ready; a request that cannot be answered is not charged. A payment that cannot be held first (its payment method does not allow it, or payments are not being held at that time) is charged when the payment is sent, and refunded if the request cannot be answered.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.50"
          },
          "protocols": [
            {
              "mpp": {
                "method": "stripe",
                "intent": "charge",
                "currency": "usd"
              }
            }
          ],
          "offers": [
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "50",
              "currency": "usd",
              "description": "One answer, paid by card or Link"
            }
          ]
        },
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "description": "The payment credential: the word Payment, then base64url JSON holding the challenge from the 402 reply, echoed, and the payment token. Omit it on the first request to receive the challenge.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Question"
              },
              "example": {
                "question": "What is ETH trading at, and what does on-chain activity show today?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer. The Payment-Receipt header names the payment that paid for it.",
            "headers": {
              "Payment-Receipt": {
                "description": "The receipt, base64url JSON: method, reference, status, timestamp.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Answer"
                }
              }
            }
          },
          "400": {
            "description": "The body is not one question of 1 to 2,000 characters. Nothing was charged.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "headers": {
              "WWW-Authenticate": {
                "description": "The challenge to pay: Payment id, realm, method=\"stripe\", intent=\"charge\", request (base64url JSON: amount in cents, currency, the seller's profile, payment method types), expires. Every 402 carries a new one.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "in_progress: this request is already being answered, send it again after Retry-After and do not pay again. payment_reused: this payment was made for another question.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "410": {
            "description": "answer_expired: more than 15 minutes have passed since this payment was first sent. payment_released: the hold was released and nothing was charged. payment_refunded: the request could not be answered and its payment is being refunded. Send the request with a new payment.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests or card payments from this address, card payments from it slowed after several were refused or could not be answered, or too many card payments being made at once. Wait the seconds in Retry-After. Nothing was charged.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "payment_check_unavailable or settlement_pending: the payment is being confirmed, send the same request again after Retry-After and do not pay again. answer_failed: the answer could not be produced; the message says whether anything was charged. busy: at a limit or out of time; the message says whether the payment was kept.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/x402/plan": {
      "post": {
        "operationId": "buyAccount",
        "summary": "Buy an agent an account of its own, or renew one, paid in USDC",
        "description": "Its own Tragent, which researches, decides and trades on Base within the account's rules, and its own wallet, owned by the P-256 owner key the buyer keeps. Money can leave the wallet only to sendTo, the one address fixed at purchase (by default the paying wallet). Paid first: the account is made once the payment is collected. Renew with {\"renew\": \"agt_...\"}.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "20.000000"
          },
          "protocols": [
            {
              "x402": {
                "x402Version": 2,
                "scheme": "exact",
                "network": "eip155:8453",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "assetSymbol": "USDC"
              }
            }
          ]
        },
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "description": "The signed x402 payment, base64 JSON. Omit it on the first request to receive the payment requirement.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanRequest"
              },
              "example": {
                "ownerKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…",
                "sendTo": "0x8f3e2d1c0b9a8f7e6d5c4b3a2918f7e6d5c4b3a2"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The account: made, or renewed. The same payment again returns the same account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "400": {
            "description": "invalid_body: the body buys or renews nothing (an ownerKey that is not a P-256 public key, a bad sendTo, or sendTo missing by card). Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "no_such_account: a renewal names no account. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "in_progress: this account is already being made, send the same request again after Retry-After. payment_reused: this payment was made for another request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "payment_spent: more than 15 minutes have passed since this payment was first sent. payment_refunded: the account could not be made and the payment is being refunded. Do not pay again for the same account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "account_failed: the account could not be made yet; the message says whether the payment was kept for a retry. settlement_pending or payment_check_unavailable: the payment is being confirmed, send the same request again and do not pay again. busy: at a limit or paused.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required, or the payment was not accepted. The PAYMENT-REQUIRED header holds what to pay.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "The payment requirement, base64 JSON (x402 version 2), paid first (paymentFlow upfront).",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mpp/plan": {
      "post": {
        "operationId": "buyAccountByCard",
        "summary": "Buy an agent an account of its own, or renew one, paid by card",
        "description": "The same account as /api/v1/x402/plan, paid by card or Link balance through a Link wallet with the Machine Payments Protocol. It is charged when the payment is sent, never held, and sendTo is required (a card has no address of its own).",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "20.00"
          },
          "protocols": [
            {
              "mpp": {
                "method": "stripe",
                "intent": "charge",
                "currency": "usd"
              }
            }
          ],
          "offers": [
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "2000",
              "currency": "usd",
              "description": "An account for an agent, 30 days"
            }
          ]
        },
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "description": "The payment credential: the word Payment, then base64url JSON holding the challenge from the 402 reply, echoed, and the payment token.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanRequest"
              },
              "example": {
                "ownerKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…",
                "sendTo": "0x8f3e2d1c0b9a8f7e6d5c4b3a2918f7e6d5c4b3a2"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The account: made, or renewed. The same payment again returns the same account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "400": {
            "description": "invalid_body: the body buys or renews nothing (an ownerKey that is not a P-256 public key, a bad sendTo, or sendTo missing by card). Nothing was charged.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "no_such_account: a renewal names no account. Nothing was charged.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "in_progress: this account is already being made, send the same request again after Retry-After. payment_reused: this payment was made for another request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "410": {
            "description": "payment_spent: more than 15 minutes have passed since this payment was first sent. payment_refunded: the account could not be made and the payment is being refunded. Do not pay again for the same account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait the seconds in Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "account_failed: the account could not be made yet; the message says whether the payment was kept for a retry. settlement_pending or payment_check_unavailable: the payment is being confirmed, send the same request again and do not pay again. busy: at a limit or paused.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "headers": {
              "WWW-Authenticate": {
                "description": "The challenge to pay: Payment id, realm, method=\"stripe\", intent=\"charge\", request (base64url JSON: amount in cents, currency, the seller's profile), expires.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/keys": {
      "post": {
        "operationId": "issueKey",
        "summary": "Issue an API key to a request the owner key signs",
        "description": "Sign the UTF-8 text \"tragent-agent-key-v1\\n<account>\\n<nonce>\\n<expiresAtMs>\" with the owner key (ECDSA P-256 over SHA-256, DER, base64). A signed request works once and expires at most ten minutes ahead. A new key replaces the account's earlier one. No key is needed for this call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The key, shown once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyReply"
                }
              }
            }
          },
          "401": {
            "description": "signature_invalid: not signed by this account's owner key, expired, or already used. Sign a new request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: too many key requests from this caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/v1/agent/account": {
      "get": {
        "operationId": "getAccount",
        "summary": "Read the account",
        "description": "The plan, the credits left, the wallet and what it holds, and recent activity.",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountDetail"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: no valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: too many calls. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/ask": {
      "post": {
        "operationId": "askAccount",
        "summary": "Send one message to the account's Tragent",
        "description": "One chat turn answered as one JSON reply. Ask it to research, to decide, or to trade: actions lists every trade or send the turn made and where each stands. The same clientMessageId again returns the same reply and never runs the turn twice.",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The reply.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TurnReply"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: no valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: too many calls. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "202": {
            "description": "Still running: send the same request, with the same clientMessageId, again in a few seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Running"
                }
              }
            }
          },
          "400": {
            "description": "invalid_body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "plan_ended or credits_exhausted: renew the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "in_progress: this message is being answered. turn_unfinished: its turn did not finish; read /account, then send a new message with a new id. agent_unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AskMessage"
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/withdraw": {
      "post": {
        "operationId": "withdraw",
        "summary": "Send from the wallet to its one address",
        "description": "To the sendTo address fixed at purchase, and nowhere else, with or without a plan or credits. The same requestId again is the same withdrawal, never a second one.",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The withdrawal and where it stands.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawalReply"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: no valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: too many calls. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "202": {
            "description": "Still being made: send the same request, with the same requestId, again in a few seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawalReply"
                }
              }
            }
          },
          "400": {
            "description": "invalid_body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The withdrawal was refused; the message says why.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Withdrawal"
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/export/prepare": {
      "post": {
        "operationId": "prepareExport",
        "summary": "Prepare an export of the wallet's key",
        "description": "Returns the exact request the owner key must sign to export the wallet's private key, encrypted to the one-time P-256 key given, and until when (five minutes).",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "What to sign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportPrepared"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: no valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: too many calls. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExportPrepare"
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/export": {
      "post": {
        "operationId": "export",
        "summary": "Export the wallet's key",
        "description": "The prepared request, signed by the owner key. The reply is ciphertext only the one-time key opens. Open with or without a plan.",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The encrypted key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportReply"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: no valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: too many calls. Wait the seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExportRequest"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Question": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "question"
        ],
        "properties": {
          "question": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000,
            "description": "One question about token prices or on-chain activity, in plain words. Include any coin, contract address, wallet address or time frame it is about."
          }
        }
      },
      "Answer": {
        "type": "object",
        "required": [
          "id",
          "answer",
          "sources",
          "asOf"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "answer": {
            "type": "string",
            "description": "The answer, in Markdown."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "label"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "asOf": {
            "type": "string",
            "format": "date-time",
            "description": "When the answer was produced."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "A problem document (RFC 9457) that also carries the API's own error object.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "error"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "PlanRequest": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "ownerKey"
            ],
            "properties": {
              "ownerKey": {
                "type": "string",
                "description": "A P-256 public key you keep, base64 SPKI DER. It owns the account and its wallet."
              },
              "sendTo": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$",
                "description": "The one address on Base money may ever leave the wallet to, fixed for good. By default the wallet that pays in USDC; required by card."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "renew"
            ],
            "properties": {
              "renew": {
                "type": "string",
                "pattern": "^agt_[A-Za-z0-9_-]{22}$",
                "description": "An account to extend by another 30 days."
              }
            }
          }
        ]
      },
      "Account": {
        "type": "object",
        "required": [
          "id",
          "account",
          "wallet",
          "sendTo",
          "plan",
          "credits",
          "asOf"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "account": {
            "type": "string",
            "pattern": "^agt_[A-Za-z0-9_-]{22}$"
          },
          "wallet": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "network": {
                "type": "string",
                "enum": [
                  "base"
                ]
              }
            }
          },
          "sendTo": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "plan": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "ended"
                ]
              },
              "endsAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "credits": {
            "type": "object",
            "properties": {
              "left": {
                "type": "number"
              }
            }
          },
          "next": {
            "type": "object"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "KeyRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "account",
          "nonce",
          "expiresAtMs",
          "signature"
        ],
        "properties": {
          "account": {
            "type": "string",
            "pattern": "^agt_[A-Za-z0-9_-]{22}$"
          },
          "nonce": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{16,64}$"
          },
          "expiresAtMs": {
            "type": "integer"
          },
          "signature": {
            "type": "string",
            "description": "base64 DER ECDSA P-256 signature over SHA-256 of the key request text."
          }
        }
      },
      "KeyReply": {
        "type": "object",
        "required": [
          "key",
          "account"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^tgk_[A-Za-z0-9_-]{43}$"
          },
          "account": {
            "type": "string",
            "pattern": "^agt_[A-Za-z0-9_-]{22}$"
          }
        }
      },
      "AccountDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Account"
          },
          {
            "type": "object",
            "properties": {
              "holdings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "amount": {
                      "type": "number"
                    },
                    "usd": {
                      "type": "number"
                    }
                  }
                }
              },
              "totalUsd": {
                "type": "number"
              },
              "recent": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "at": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "AskMessage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "clientMessageId"
        ],
        "properties": {
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000
          },
          "clientMessageId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{8,64}$",
            "description": "Names the message: sent again, it returns the same reply."
          },
          "session": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,64}$",
            "description": "Keeps a conversation going (default api)."
          }
        }
      },
      "TurnReply": {
        "type": "object",
        "required": [
          "message",
          "actions"
        ],
        "properties": {
          "message": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "description": "Markdown."
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "status"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          },
          "unfinished": {
            "type": "boolean",
            "description": "The turn stopped after it began moving value: its requests are listed, and the message is never run again."
          }
        }
      },
      "Running": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "running"
            ]
          },
          "clientMessageId": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Withdrawal": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "token",
          "amount",
          "requestId"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "USDC, ETH, or a token address on Base."
          },
          "amount": {
            "type": "string",
            "description": "How much of the token, as a decimal string."
          },
          "requestId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{8,64}$",
            "description": "Names the withdrawal: sent again, it is the same one."
          }
        }
      },
      "WithdrawalReply": {
        "type": "object",
        "properties": {
          "request": {
            "type": [
              "string",
              "null"
            ]
          },
          "requestId": {
            "type": "string"
          },
          "to": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "done",
              "running",
              "pending"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ExportPrepare": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "recipientPublicKey"
        ],
        "properties": {
          "recipientPublicKey": {
            "type": "string",
            "description": "A one-time P-256 public key, base64 SPKI DER, to encrypt the export to."
          }
        }
      },
      "ExportPrepared": {
        "type": "object",
        "required": [
          "payload",
          "expiresAtMs"
        ],
        "properties": {
          "payload": {
            "type": "string",
            "description": "base64 bytes the owner key must sign."
          },
          "expiresAtMs": {
            "type": "integer"
          }
        }
      },
      "ExportRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "recipientPublicKey",
          "expiresAtMs",
          "signature"
        ],
        "properties": {
          "recipientPublicKey": {
            "type": "string"
          },
          "expiresAtMs": {
            "type": "integer"
          },
          "signature": {
            "type": "string",
            "description": "base64 DER ECDSA P-256 signature over SHA-256 of the payload."
          }
        }
      },
      "ExportReply": {
        "type": "object",
        "required": [
          "ciphertext",
          "encapsulatedKey"
        ],
        "properties": {
          "ciphertext": {
            "type": "string"
          },
          "encapsulatedKey": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "agentKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An account's API key, tgk_..., issued by POST /api/v1/agent/keys."
      }
    }
  }
}
