AnyGas Best Execution API

openapi: 3.2.0
info:
  title: Anygas Xyz Best Execution API
  version: 3.28.2
  contact:
    name: Robyn AnyGas
    url: https://anygas.xyz
  license:
    name: Service terms
    url: https://anygas.xyz/svc/api/terms
  x-lastUpdated: '2026-07-29'
  description: 'Operations tagged best-execution across 2 of this provider''s published API definitions: anygas-openapi.json, anygas-xyz-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.anygas.xyz/svc
  description: Production gateway (also https://anygas.xyz/svc)
tags:
- name: best-execution
  description: Multi-rail comparator and goal-based intent solver (read-only)
paths:
  /api/route/compare:
    get:
      tags:
      - best-execution
      summary: Compare every rail for a lane (query form)
      description: 'Quotes every rail that can serve a lane (aggregators + Allbridge + Chainflip) in parallel, ranks by net destination output and flags the best. Read-only, nothing signed. Adds effectiveFeePct, qualityScore, guard and a 12s cached flag. Rate limit 30/min.


        Includes Robyn''s OWN float lane as a ranked candidate, not just third-party bridges. The lane is quoted from inventory Robyn already holds on the destination chain, so it needs no external API and still answers when every aggregator is rate-limited or down. The `firstParty` block states the first-party price against the best third-party price for that exact request, so the independence claim is checkable per call. Pass `excludeRails: ["floatlane"]` to compare only third-party rails (used internally when moving Robyn''s own inventory, which the lane cannot do).'
      operationId: compareRoutesGet
      parameters:
      - name: fromChain
        in: query
        required: true
        schema:
          type: string
        example: '42161'
      - name: toChain
        in: query
        required: true
        schema:
          type: string
        example: solana
      - name: fromToken
        in: query
        required: false
        schema:
          type: string
        example: USDC
      - name: toToken
        in: query
        required: false
        schema:
          type: string
        example: USDC
      - name: amount
        in: query
        required: true
        schema:
          type: string
        example: '50000000'
      - name: toAddress
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Ranked rails
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareResult'
    post:
      tags:
      - best-execution
      summary: Compare every rail for a lane (JSON body)
      description: 'Same as the GET form; accepts the RouteRequest body. Read-only.


        Includes Robyn''s OWN float lane as a ranked candidate, not just third-party bridges. The lane is quoted from inventory Robyn already holds on the destination chain, so it needs no external API and still answers when every aggregator is rate-limited or down. The `firstParty` block states the first-party price against the best third-party price for that exact request, so the independence claim is checkable per call. Pass `excludeRails: ["floatlane"]` to compare only third-party rails (used internally when moving Robyn''s own inventory, which the lane cannot do).'
      operationId: compareRoutesPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: Ranked rails
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareResult'
        '400':
          description: Malformed request (missing fromChain/toChain/amount). Body carries errorCode + suggestedAction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: RATE_LIMITED — honour Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.anygas.xyz/svc
      description: Production gateway (also https://anygas.xyz/svc)
  /api/intent/solve:
    post:
      tags:
      - best-execution
      summary: Goal-based source picker (JSON body)
      description: State a goal, a destination and 1–10 candidate funding sources; the solver reads /compare once per source and ranks them, returning a plan with ready-to-POST execute params. It NEVER executes. Rate limit 20/min.
      operationId: solveIntentPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentRequest'
      responses:
        '200':
          description: Ranked plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntentPlan'
    get:
      tags:
      - best-execution
      summary: Goal-based source picker (query form)
      description: Query-string form of intent/solve. Encode the sources as JSON in the `from` param.
      operationId: solveIntentGet
      parameters:
      - name: toChain
        in: query
        required: true
        schema:
          type: string
        example: '8453'
      - name: toToken
        in: query
        required: true
        schema:
          type: string
        example: USDC
      - name: from
        in: query
        required: true
        schema:
          type: string
        description: JSON array of sources, url-encoded.
        example: '[{"chain":42161,"token":"USDC","amount":"5000000"}]'
      - name: goal
        in: query
        required: false
        schema:
          type: string
          enum:
          - max-output
          - cheapest
          - fastest
      - name: amount
        in: query
        required: false
        schema:
          type: string
      - name: toAddress
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Ranked plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntentPlan'
    servers:
    - url: https://api.anygas.xyz/svc
      description: Production gateway (also https://anygas.xyz/svc)
  /api/route/why:
    post:
      tags:
      - best-execution
      summary: Why this route won — and what it actually beat
      operationId: routeWhy
      description: 'Every router in this space returns a winner. None tells you what it beat, or whether it beat anything at all. "Best route" is presented identically when five rails competed and the cheapest won, and when four rails failed to answer and the survivor was declared best by default — so an agent cannot tell a good price from the only price. This returns the whole decision: every rail that quoted, what each would deliver, the margin the winner won by, and which rails stayed SILENT and why. CHECK `wasCompetitive` BEFORE PRESENTING A PRICE AS GOOD. When false, exactly one rail answered and "best" means "only". Rails listed in `silentRails` did NOT lose — they failed to answer (down, rate-limited, missing credentials) and each carries its reason. Counting silence as defeat is how a router flatters its own coverage. Signed, so the rationale can be archived. Silent rails are CLASSIFIED: `status:"not-configured"` (missing credentials — will never recover on retry, needs an operator) versus `status:"degraded"` (rate limit or cooldown — may self-heal). Each carries `recoversOnRetry` and a `remedy`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: 'Signed rationale: chosen, runnerUp, margin, candidates, silentRails, wasCompetitive'
          content:
            application/json:
              schema:
                type: object
        '502':
          description: Comparison unavailable
          content:
            application/json:
              schema:
                type: object
    servers:
    - url: https://api.anygas.xyz/svc
      description: Production gateway (also https://anygas.xyz/svc)
  /api/route/why/verify:
    post:
      tags:
      - best-execution
      summary: Verify a signed routing rationale
      operationId: verifyWhy
      description: Recomputes the digest from the submitted decision, so inflating the winner's delivery, renaming the winning rail, erasing the silent rails or flipping `wasCompetitive` all invalidate it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: valid, recomputed digest, recovered signer
          content:
            application/json:
              schema:
                type: object
    servers:
    - url: https://api.anygas.xyz/svc
      description: Production gateway (also https://anygas.xyz/svc)
  /api/route/improve:
    post:
      tags:
      - best-execution
      summary: What would make this transfer cheaper?
      operationId: improveCost
      description: 'Every router answers "what does this cost?". None answers "what should I change?". An agent handed a price can only pay it or give up — yet the price is usually a consequence of choices it did not know it was making: the destination chain (payout gas varies by more than 1000x), the size (a fixed cost is ruinous on a small transfer and trivial on a large one), whether the instant float lane applied, and whether the rails that would have competed were even available. Every suggestion carries the REAL saving in base units, computed from the same cost table the router charges from. CRITICAL: suggestions flagged `changesOutcome: true` move WHERE THE MONEY LANDS. Do not apply them as pure cost savings — telling someone to send to a different chain is not a cost tip if that is not where the funds were needed. If nothing can be improved, it says so instead of inventing filler.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: Quantified suggestions, each declaring changesOutcome
          content:
            application/json:
              schema:
                type: object
        '400':
          description: amount is required
          content:
            application/json:
              schema:
                type: object
    servers:
    - url: https://api.anygas.xyz/svc
      description: Production gateway (also https://anygas.xyz/svc)
  /api/route/settle:
    post:
      tags:
      - best-execution
      summary: Plan a private, gasless, best-route settlement in one call
      description: The one-verb primitive. Returns the best route (all rails compared), the gasless method, the privacy posture that will apply (API-relay + private mempool or sequencer-privacy + uniform shape), and what the settlement receipt will prove. Planning only - it does not broadcast; sign+submit via /api/route/execute.
      operationId: postApiRouteSettle
      x-operation-id-source: derived
    servers:
    - url: https://api.anygas.xyz/svc
      description: Production gateway (also https://anygas.xyz/svc)
components:
  schemas:
    IntentRequest:
      type: object
      required:
      - toChain
      - toToken
      - from
      properties:
        toChain:
          oneOf:
          - type: string
          - type: integer
          example: 8453
        toToken:
          type: string
          example: USDC
        from:
          type: array
          description: 1–10 candidate sources.
          items:
            type: object
            properties:
              chain: {}
              token:
                type: string
              amount:
                type: string
          example:
          - chain: 42161
            token: USDC
            amount: '5000000'
          - chain: 10
            token: USDC
            amount: '5000000'
        goal:
          type: string
          enum:
          - max-output
          - cheapest
          - fastest
          default: max-output
        amount:
          type: string
          description: Shared amount if sources omit their own.
        toAddress:
          type: string
          description: Recipient, echoed into plan.execute.
    Error:
      type: object
      description: Every error carries a stable errorCode plus recovery metadata. The legacy `error` string is retained for backward compatibility - branch on errorCode.
      properties:
        error:
          type: string
          description: human-readable message (legacy field)
        errorCode:
          type: string
          example: INSUFFICIENT_FLOAT
          description: stable machine code; see GET /api/errors for the full catalogue
        retryable:
          type: boolean
        retryAfterMs:
          type: integer
          description: present when the failure is transient
        suggestedAction:
          type: string
          description: what the caller should actually do next
        docs:
          type: string
      required:
      - error
    CompareResult:
      type: object
      properties:
        lane:
          type: object
          properties:
            fromChain:
              type: string
            toChain:
              type: string
            applicableRails:
              type: array
              items:
                type: string
            estOutUnit:
              type: string
        quotes:
          type: array
          items:
            type: object
            properties:
              rail:
                type: string
              ok:
                type: boolean
              estOut:
                type: string
              etaSeconds:
                type: number
              best:
                type: boolean
              effectiveFeePct:
                type: number
              qualityScore:
                type: integer
            additionalProperties: true
        best:
          type: string
          example: allbridge
        comparedRails:
          type: integer
          example: 2
        railsAttempted:
          type: integer
          example: 2
        guard:
          type: object
          properties:
            ok:
              type: boolean
            effectiveFeePct:
              type: number
            thresholdPct:
              type: number
            recommendedMinInput:
              type: string
        cached:
          type: boolean
          example: false
      additionalProperties: true
    IntentPlan:
      type: object
      properties:
        goal:
          type: string
          example: max-output
        to:
          type: object
          properties:
            chain: {}
            token:
              type: string
        plan:
          type: object
          nullable: true
          description: Winner (null if nothing quoted). plan.execute is ready to POST to /api/route/execute.
          properties:
            from:
              type: object
              additionalProperties: true
            rail:
              type: string
            estOut:
              type: string
            qualityScore:
              type: integer
            execute:
              type: object
              additionalProperties: true
          additionalProperties: true
        alternatives:
          type: array
          items:
            type: object
            additionalProperties: true
        skipped:
          type: array
          items:
            type: object
            additionalProperties: true
        sourcesConsidered:
          type: integer
          example: 2
        note:
          type: string
      additionalProperties: true
    RouteRequest:
      type: object
      required:
      - fromChain
      - toChain
      - amount
      properties:
        fromChain:
          description: 'Source node: EVM chain id or one of "solana"/"stellar"/"bitcoin".'
          oneOf:
          - type: string
          - type: integer
          example: 42161
        toChain:
          description: Destination node.
          oneOf:
          - type: string
          - type: integer
          example: bitcoin
        amount:
          type: string
          description: Source-token smallest units.
          example: '50000000'
        fromToken:
          type: string
          description: Symbol or address; omit for native.
          example: USDC
        toToken:
          type: string
          description: Symbol or address; omit for native.
          example: BTC
        toAddress:
          type: string
          description: Recipient; defaults to fromAddress.
        fromAddress:
          type: string
          description: Quote origin; anonymous default used if omitted.
        slippage:
          type: number
          description: Fraction, e.g. 0.005.
        token:
          type: string
          description: 'Shorthand: sets BOTH fromToken and toToken (e.g. "USDC"). Accepted on POST bodies and as a GET query parameter. Explicit fromToken/toToken win when present.'
          example: USDC
x-refined-from:
- anygas-openapi.json
- anygas-xyz-openapi.json