API Endpoints

For a high-level overview on how to integrate these API endpoints see Integration Guide.

Lookup Payment

Lookup Payment

GET https://yodl.me/api/v1/tx/:chainId/:txHash

This endpoint looks up the given transaction in our database and returns an array of payments in an easy to read JSON format. The yodlFee value is a decimal value in terms of the token amount.

If price feeds are provided, conversion will be in the form of chainlink:XXXYYY where XXX is the invoice currency, and YYY is the token currency. The price feeds will be in the order they were used to convert from invoice currency to the token currency. The price feed name will be in the format $baseCurrency$quoteCurrency and their rates will all be in terms of the quote currency (usually USD).

Path Parameters

Name	Type	Description
:chainId*	String
:txHash*	String

Headers

Name	Type	Description
Authorization*	String	API Key

200: OK Successful response

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "test",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "USDC", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "1.00",
        "value": "1000000"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "0.9975",
        "value": "997500"
      },
      "totalFees": {
        "formatted": "0.0025",
        "value": "2500"
      },
      "fees": [
        {
          // fee charged by YODL
          "type": "YodlFee",
          "formatted": "0.002",
          "value": "2000"
        },
        {
          // extra fee charged by third-party
          "type": "ExtraFee",
          "formatted": "0.0005",
          "value": "500"
        }
      ],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "USD",
      "conversion": "",
      "priceFeeds": [],
      // whether a sufficient number of blocks have passed for the tx to be considered final
      // see Finality section
      "final": true
    }
  ]
}

200: OK Successful payment with one price feeds

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "test",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "USDC", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "1.05565",
        "value": "1055650"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "1.053539",
        "value": "1053539"
      },
      "totalFees": {
        "formatted": "0.002111",
        "value": "2111"
      },
      "fees": [
        {
          // fee charged by YODL
          "type": "YodlFee",
          "formatted": "0.002111",
          "value": "2111"
        }
      ],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "EUR",	
      "conversion": "chainlink:EURUSD",
      "priceFeeds": [
        {
          "name": "EURUSD",
          "contract": "0xab70BCB260073d036d1660201e9d5405F5829b7a",
          "rate": "1.05565"
        }
      ],
      // whether a sufficient number of blocks have passed for the tx to be considered final
      // see Finality section
      "final": true
    }
  ]
}

200: OK Successful payment with two price feeds

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "test",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "EURe", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "1.045246858849634651",
        "value": "1045246858849634651"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "1.045246858849634651",
        "value": "1045246858849634651"
      },
      "totalFees": {
        "formatted": "0",
        "value": "0"
      },
      "fees": [],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "CHF",	
      "conversion": "chainlink:CHFEUR",
      "priceFeeds": [
        {
          "name": "CHFUSD",
          "contract": "0xFb00261Af80ADb1629D3869E377ae1EEC7bE659F",
          "rate": "1.10933617"
        },
        {
          "name": "EURUSD",
          "contract": "0xab70BCB260073d036d1660201e9d5405F5829b7a",
          "rate": "1.061315"
        }
      ],
      // whether a sufficient number of blocks have passed for the tx to be considered final
      // see Finality section
      "final": true
    }
  ]
}

400: Bad Request One or more of the URL parameters are invalid

{
  "error": "Invalid query parameters",
  "details": [
    {
      "code": "custom",
      "message": "Address must start with '0x' and have 60 characters",
      "path": [
        "txHash"
      ]
    }
  ]
}

401: Unauthorized Valid 'Authorization' header is not present

404: Not Found Transaction is not in our system

Lookup & Verify Payment

Lookup and verify a payment against given parameters

POST https://yodl.me/api/v1/verify

This endpoint behaves similarly to the Lookup endpoint with the notable addition of performing server-side payment verification checks. Instead of passing through transaction details in the URL, a JSON payload must be sent.

This endpoint will verify that a malicious user has not interferred and manipulated the payment.

Headers

Name	Type	Description
Authorization*	String	API Key
Content-Type*	String	application/json

Request Body

Name	Type	Description
chainId*	number	id of the chain on which the transaction took place
txHash*	string	transaction hash
invoiceAmount*	number/string	amount of the invoice with decimals eg. 1.23
invoiceCurrency*	string	uppercase currency for the invoice eg. USD
address*	string	receiver address or yodl.me handle

200: OK Successful response

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "USDC", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "0.737055",
        "value": "737055"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "0.737055",
        "value": "737055"
      },
      "totalFees": {
        "formatted": "0",
        "value": "0"
      },
      "fees": [],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "CAD",	
      "conversion": "chainlink:CADUSD",
      "priceFeeds": [
        {
          "name": "CADUSD",
          "contract": "0xf6DA27749484843c4F02f5Ad1378ceE723dD61d4",
          "rate": "0.7370555"
        }
      ],
      // whether a sufficient number of blocks have passed for the tx to be considered final
      // see Finality section
      "final": true
      "verified": true,
      "verificationErrors": []
    }
  ]
}

400: Bad Request One or more of the URL parameters are invalid

{
    "error": "Invalid query parameters",
    "details": [
        {
            "code": "custom",
            "message": "Address must start with '0x' and have 60 characters",
            "path": [
                "txHash"
            ]
        }
    ]
}

404: Not Found Transaction is not found in our system

409: Conflict Payment(s) did not match the given payload

Verification errors can one or more of:

Payment does not match link configuration

Invalid payment address

Invalid payment currency

Invalid payment amount

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "USDC", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "0.737055",
        "value": "737055"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "0.737055",
        "value": "737055"
      },
      "totalFees": {
        "formatted": "0",
        "value": "0"
      },
      "fees": [],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "CAD",	
      "conversion": "chainlink:CADUSD",
      "priceFeeds": [
        {
          "name": "CADUSD",
          "contract": "0xf6DA27749484843c4F02f5Ad1378ceE723dD61d4",
          "rate": "0.7370555"
        }
      ],
      "verified": false,
      "verificationErrors": [
        "Payment does not match link configuration"
      ]
    }
  ]
}

Notes

It is technically possible that a (blockchain) transaction can contain mulitple YODL payments. Therefore the API endpoints return an array of payments.

Finality

There are multiple definitions out there for finality, some more strict than others. In order to be practical, we will look at the likelihood of a reorg after a certain number of transactions have passed.

Currently, the confirmations we use are as follows:

Chain Name	Chain Id	Confirmations	Duration
Mainnet	1	3	~36 seconds
Optimism	10	48	~96 seconds
Gnosis	100	1	~5 seconds
Polygon	137	50	~100 seconds
Arbitrum One	42161	1600	~8 minutes

Types

These are likely to change and are provided as a snapshot to the current state of types.

export enum OnCompleteActionType {
  NOTHING = "NOTHING",
  REDIRECT = "REDIRECT",
  CLOSE_WINDOW = "CLOSE_WINDOW",
}

export type OnCompleteAction =
  | { type: OnCompleteActionType.NOTHING }
  | {
      type: OnCompleteActionType.REDIRECT;
      payload: {
        url: string;
      };
    }
  | {
      type: OnCompleteActionType.CLOSE_WINDOW;
      payload: {
        delayMilliseconds: number;
      };
    };

export type CoinConfig = {
  chainId: number;
  defaultAddress?: string;
  tokens: {
    symbol: string;
    address?: string;
  }[];
};

export type LinkConfig = {
  coins: CoinConfig[];
  onCompleteAction?: OnCompleteAction;
};

export type PriceFeed = {
  name: string;
  contract: string;
  rate: string;
};

export type LookupTxDetails = {
  chainId: number;
  txHash: string;
  memo: string;
  receiver: string;
  tokenSymbol: string;
  tokenAmountGross: string;
  tokenAmountNet: string;
  tokenAmountGrossNative: string;
  tokenAmountNetNative: string;
  yodlFee: string;
  invoiceAmount: string;
  invoiceCurrency: string;
  conversion: string;
  priceFeeds: PriceFeed[];
};

export type AccountsResponse = {
	address: string;
	config: LinkConfig;
	handle: string;
};

export type LookupResponse = LookupTxDetails[];

export type VerifyDetails = LookupDetails & {
	verified: boolean;
	verificationErrors: string[]
};

export type VerifyResponse = VerifyDetails[];