{
  "openapi": "3.1.0",
  "info": {
    "title": "Signalbound Agent Tools",
    "version": "1.0.0",
    "description": "Holder-gated agent intelligence, NFT discovery, portfolio, offer, and market radar APIs.",
    "contact": {
      "name": "Signalbound",
      "email": "nrlnft@gmail.com",
      "url": "https://signalbound.art/tools"
    },
    "x-guidance": "Choose the operation that matches the task, provide a Signalbound token owned by the authenticated caller, and follow the endpoint's x402 challenge."
  },
  "servers": [
    {
      "url": "https://api.signalbound.art"
    }
  ],
  "paths": {
    "/intel": {
      "post": {
        "operationId": "signalboundIntel",
        "summary": "Read a Signalbound agent profile and mission brief",
        "description": "Returns agent profile, signal analysis, and mission brief for a Signalbound identity on Ethereum. Requires holding a Signalbound NFT. Predicate-gated via ERC-8257.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID (1-6666)"
                  }
                },
                "required": [
                  "tokenId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tokenId": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "rarity_tier": {
                      "type": "string"
                    },
                    "rarity_score": {
                      "type": "number"
                    },
                    "edition": {
                      "type": "string"
                    },
                    "traits": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "tokenId",
                    "name",
                    "rarity_tier",
                    "traits",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    },
    "/drop-radar": {
      "post": {
        "operationId": "signalboundDropRadar",
        "summary": "Scan OpenSea NFT drops and mint stages",
        "description": "Surfaces only verifiably active and upcoming OpenSea NFT drops with stage pricing, supply, and optional wallet mint eligibility. Ended, undated, and stale open-ended drops are excluded. Requires holding a Signalbound NFT. Predicate-gated via ERC-8257.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID used for ERC-7496 clearance-gated access. The authenticated caller must own it."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "all",
                      "featured",
                      "upcoming",
                      "recently_minted"
                    ],
                    "description": "Discovery feed to scan. Regardless of feed, only verifiably active or future drops are returned."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "description": "Maximum drops to return (default 20)."
                  },
                  "chain": {
                    "type": "string",
                    "description": "Optional chain filter (e.g. ethereum, base, polygon). Omit for all chains."
                  },
                  "scanChains": {
                    "type": "boolean",
                    "description": "When true, radar also queries known OpenSea chains individually to catch drops that do not appear in the unfiltered feed (default true)."
                  },
                  "enrich": {
                    "type": "boolean",
                    "description": "Fetch extra per-drop detail data when needed (default false). The radar uses OpenSea list-stage data by default for faster scans."
                  },
                  "checkWalletEligibility": {
                    "type": "boolean",
                    "description": "When true, uses walletAddress (or the authenticated caller) to probe mint eligibility via OpenSea mint-build API."
                  },
                  "walletAddress": {
                    "type": "string",
                    "description": "Optional wallet for eligibility checks. Defaults to the SIWE-authenticated caller address."
                  },
                  "watchSlugs": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "type": "string"
                    },
                    "description": "OpenSea collection slugs to resolve directly even when they are absent from curated and trending feeds."
                  }
                },
                "required": [
                  "tokenId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "drops": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "chain": {
                            "type": "string"
                          },
                          "imageUrl": {
                            "type": "string"
                          },
                          "openseaUrl": {
                            "type": "string"
                          },
                          "contractAddress": {
                            "type": "string"
                          },
                          "totalSupply": {
                            "type": "number"
                          },
                          "maxSupply": {
                            "type": "number"
                          },
                          "remaining": {
                            "type": "number"
                          },
                          "stages": {
                            "type": "array"
                          },
                          "walletEligibility": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "generatedAt",
                    "count",
                    "drops",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    },
    "/b20-radar": {
      "post": {
        "operationId": "signalboundB20Radar",
        "summary": "Inspect Base B20 deployments and market activity",
        "description": "Watches Base's native B20 token standard (Beryl upgrade): surfaces newly deployed B20 tokens from the factory precompile and inspects any B20 token by address (name, symbol, variant, decimals, currency, supply). Requires holding a Signalbound NFT. Predicate-gated via ERC-8257.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID used for ERC-7496 clearance-gated access. The authenticated caller must own it."
                  },
                  "address": {
                    "type": "string",
                    "description": "Optional B20 token address (0xB20f...) to inspect. Omit to scan for recent deployments instead."
                  },
                  "blocksBack": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 604800,
                    "description": "How many Base blocks to scan back for new deployments (default 302400, roughly 7 days; max roughly 14 days)."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "description": "Maximum tokens to return (default 25)."
                  }
                },
                "required": [
                  "tokenId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generatedAt": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "detectedCount": {
                      "type": "integer"
                    },
                    "truncated": {
                      "type": "boolean"
                    },
                    "fromBlock": {
                      "type": "string"
                    },
                    "toBlock": {
                      "type": "string"
                    },
                    "blocksBack": {
                      "type": "integer"
                    },
                    "tokens": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "address": {
                            "type": "string"
                          },
                          "variant": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "symbol": {
                            "type": "string"
                          },
                          "decimals": {
                            "type": "number"
                          },
                          "totalSupply": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "initialized": {
                            "type": "boolean"
                          },
                          "market": {
                            "type": "object",
                            "description": "Live market metrics (Dexscreener): price, 24h volume, liquidity, 24h change, transactions, market cap, a link, plus a market-depth risk assessment.",
                            "properties": {
                              "priceUsd": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "volumeH24": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "liquidityUsd": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "priceChangeH24": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "txns24": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "marketCap": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "risk": {
                                "type": "object",
                                "description": "level (low|elevated|high), 24h volume ÷ liquidity, and flags such as thin liquidity or an extreme 24h move.",
                                "properties": {
                                  "level": {
                                    "type": "string"
                                  },
                                  "volToLiq": {
                                    "type": [
                                      "number",
                                      "null"
                                    ]
                                  },
                                  "flags": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  }
                                }
                              },
                              "url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "generatedAt",
                    "count",
                    "tokens",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    },
    "/robinhood-radar": {
      "post": {
        "operationId": "signalboundRobinhoodRadar",
        "summary": "Scan active assets on Robinhood Chain",
        "description": "Radar for Robinhood Chain: surfaces the most active community tokens and tokenized assets right now, ranked by 24h volume, with liquidity, market cap, and price action. Requires holding a Signalbound NFT with Elite (Epic+) clearance. Predicate-gated via ERC-8257.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID used for ERC-7496 clearance-gated access. The authenticated caller must own it (Elite clearance)."
                  },
                  "address": {
                    "type": "string",
                    "description": "Optional Robinhood Chain token address (0x...) to inspect a single token. Omit to scan the most active tokens instead."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 5,
                    "maximum": 30,
                    "description": "How many active tokens to return (default 15)."
                  },
                  "includeStables": {
                    "type": "boolean",
                    "description": "Include stablecoins / wrapped natives (USDG, WETH…). Off by default so real community tokens surface."
                  }
                },
                "required": [
                  "tokenId"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generatedAt": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "tokens": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "address": {
                            "type": "string"
                          },
                          "symbol": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "priceUsd": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "volume24hUsd": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "liquidityUsd": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "marketCapUsd": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "priceChange24h": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "txns24": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "risk": {
                            "type": "object",
                            "description": "Liquidity/volume risk assessment: level (low|elevated|high), 24h volume ÷ liquidity, and human-readable flags such as thin liquidity or an extreme 24h move.",
                            "properties": {
                              "level": {
                                "type": "string"
                              },
                              "volToLiq": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "flags": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    },
                    "clearance": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "generatedAt",
                    "count",
                    "tokens",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    },
    "/portfolio": {
      "post": {
        "operationId": "signalboundPortfolio",
        "summary": "Analyze a wallet NFT portfolio",
        "description": "Wallet portfolio intel: NFT holdings, received offers, and estimated value via OpenSea. Requires Rare tier or higher Signalbound agent. ERC-8257 predicate + clearance gate.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID used for ERC-7496 clearance-gated access. The authenticated caller must own it."
                  },
                  "walletAddress": {
                    "type": "string",
                    "description": "Wallet to scan. Defaults to the authenticated caller."
                  },
                  "chain": {
                    "type": "string",
                    "description": "Chain identifier (default ethereum)."
                  },
                  "nftLimit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "description": "Max NFTs to return (default 50)."
                  }
                },
                "required": [
                  "tokenId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "wallet": {
                      "type": "string"
                    },
                    "chain": {
                      "type": "string"
                    },
                    "nftCount": {
                      "type": "integer"
                    },
                    "nfts": {
                      "type": "array"
                    },
                    "offersReceived": {
                      "type": "array"
                    },
                    "estimatedValueUsd": {
                      "type": "number"
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    },
                    "clearance": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "wallet",
                    "chain",
                    "nftCount",
                    "nfts",
                    "offersReceived",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    },
    "/allowlist-scan": {
      "post": {
        "operationId": "signalboundAllowlistScan",
        "summary": "Check wallet eligibility across NFT drops",
        "description": "Batch-scans only verifiably active and upcoming OpenSea drops for wallet mint eligibility. Ended, undated, and stale open-ended drops are excluded. Requires Rare tier or higher Signalbound agent. ERC-8257 predicate + clearance gate.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID used for ERC-7496 clearance-gated access. The authenticated caller must own it."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "all",
                      "featured",
                      "upcoming",
                      "recently_minted"
                    ],
                    "description": "Discovery feed to scan. Regardless of feed, only verifiably active or future drops are returned."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "description": "Max drops to scan (default 25)."
                  },
                  "chain": {
                    "type": "string",
                    "description": "Optional chain filter."
                  },
                  "scanChains": {
                    "type": "boolean",
                    "description": "When true, scans known OpenSea chains individually in addition to the global feed (default true)."
                  },
                  "walletAddress": {
                    "type": "string",
                    "description": "Wallet to check. Defaults to authenticated caller."
                  },
                  "eligibleOnly": {
                    "type": "boolean",
                    "description": "Omit ineligible drops from ineligible array when false (default)."
                  }
                },
                "required": [
                  "tokenId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string"
                    },
                    "scanned": {
                      "type": "integer"
                    },
                    "eligibleCount": {
                      "type": "integer"
                    },
                    "eligible": {
                      "type": "array"
                    },
                    "ineligible": {
                      "type": "array"
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    },
                    "clearance": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "generatedAt",
                    "scanned",
                    "eligibleCount",
                    "eligible",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    },
    "/offer-radar": {
      "post": {
        "operationId": "signalboundOfferRadar",
        "summary": "Scan collection offers, floors, and listings",
        "description": "Collection offer and listing radar: floor, best listings, and collection offers for up to 10 slugs. Requires Epic tier or higher Signalbound agent. ERC-8257 predicate + clearance gate.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "1.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6666,
                    "description": "Signalbound token ID used for ERC-7496 clearance-gated access. The authenticated caller must own it."
                  },
                  "slugs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 10,
                    "description": "OpenSea collection slugs to scan."
                  }
                },
                "required": [
                  "tokenId",
                  "slugs"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tool response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "collections": {
                      "type": "array"
                    },
                    "brief": {
                      "type": "string"
                    },
                    "caller": {
                      "type": "string"
                    },
                    "clearance": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "count",
                    "collections",
                    "brief"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment or holder authorization required"
          },
          "403": {
            "description": "The caller does not satisfy the tool access policy"
          }
        }
      }
    }
  }
}